Permite realizar un cargo de manera segura y rápida.
Con la API de pagos realiza cargos a tus clientes de manera segura sin salir de tu sitio web.
Antes de realizar una llamada a este endpoint, asegúrate de generar un token usando el endpoint de card token si eres PCI, o por medio del método cardToken() del SDK de Checkout Transparente si no eres PCI.
Header parameters (parámetros del encabezado)
La siguiente tabla describe el esquema de los parámetros del encabezado:
|
Parámetro |
Descripción |
Tipo |
Requerido / Opcional |
Notas |
|
|
Content-Type |
Define el formato del objeto de la llamada |
application/json |
Requerido |
Solicitud en formato JSON |
|
|
Authorization |
Especifica el token de acceso |
String |
Requerido |
token de autenticación |
|
Body parameters (parámetros del cuerpo de la solicitud)
La siguiente tabla describe el esquema de los parámetros del body de la solicitud de pago:
|
Parámetro |
Descripción |
Tipo |
Ejemplo |
Requerido / Opcional |
Notas |
||
|
capture_method |
Modo de captura en el proceso de autorización y captura |
String |
“automatic” |
Opcional |
Posibles valores: automatic o manual El default es automatic |
||
|
currency |
Código de moneda en formato ISO 4217 alfabético |
String |
“MXN” |
Requerido |
Únicamente puede ser MXN |
||
|
amount |
Monto a cobrar |
Float |
100.50 |
Requerido |
Acepta 2 decimales como máximo |
||
|
payment_method |
Objeto con el método de pago utilizado para completar la transacción |
Objeto |
|
|
|
||
|
|
token |
Token ID de la tarjeta |
String |
"9144bbf8-e4cb-4e14-8412-d2b4d867c509" |
Requerido |
El token que se genera por medio del endpoint de Card token |
|
|
tip_amount |
Propina sobre el precio del producto o servicio que se está pagando |
Float |
10.50 |
Opcional |
Si no hay propina se pasa un monto “0”. Acepta 2 decimales como máximo |
||
|
description |
Texto describiendo el cargo |
String |
“Venta de item #7” |
Opcional |
Formato UTF-8. Se aceptan los siguientes caracteres especiales: ~!@#$%^&*()\\=+\\\\|\\[{\\]};:'\"/?. No se aceptan emojis. Longitud mínima: 1 Longitud máxima: 255 |
||
|
external_reference |
ID de referencia de la transacción para rastrear las transacciones |
String |
“OID123456789” |
Opcional |
Longitud máxima: 36 caracteres. Caracteres especiales permitidos: Guión medio (-) y Guión bajo (_) Se permiten acentos. Los espacios en blanco serán removidos. |
||
|
installments |
Meses sin intereses |
Number |
3 |
Opcional |
Los posibles valores pueden ser: 3, 6, 9, 12, 18, 24. El valor por default es 1, lo cuál significa que el pago no será diferido a meses. |
||
|
customer |
Objeto con la información del cliente para el pago |
Objeto |
|
|
|
||
|
|
first_name |
Nombre del cliente que realiza la transacción. |
String |
"Dong" |
Opcional |
|
|
|
|
last_name |
Apellido del cliente que realiza la transacción. |
String |
"Lee" |
Opcional |
|
|
|
|
|
Correo electrónico del cliente que realiza la transacción. |
String |
"buyer @email.com" |
Requerido |
|
|
|
|
phone |
Número telefónico del cliente que realiza la transacción. |
String |
"5555555555" |
Requerido |
|
|
|
|
address |
Objeto con la dirección de facturación. |
Objeto |
|
Opcional |
|
|
|
|
|
postal_code |
Código postal. |
String |
"03800" |
Opcional |
Para AMEX este campo es obligatorio |
|
|
|
street |
Nombre de la calle. |
String |
"Av Uno" |
Opcional |
Para AMEX este campo es obligatorio |
|
|
|
number |
Número exterior del domicilio. |
String |
"104" |
Opcional |
Para AMEX este campo es obligatorio |
|
|
|
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 |
|
|
|
description |
Texto describiendo al cliente. |
String |
"Gerente de la fábrica de pintura" |
Opcional |
|
|
|
|
identification |
Objeto con los datos de la identificación del cliente. |
Objeto |
|
|
|
|
|
|
|
id |
Número de identificación. |
String |
"TE1HCSXRS01" |
Opcional |
Número de folio o número de id |
|
|
|
type |
Tipo de identificación. |
String |
"CURP" |
Opcional |
Tipos pueden ser: INE, pasaporte, CURP. |
|
webhook_url |
URL del endpoint que recibirá notificaciones webhook del link de pago. |
String |
"https://wh.co" |
Opcional |
Puedes consultar la estructura de la notificación webhook en el siguiente link. |
||
|
prevention_data |
Objeto con datos para prevención de fraude. |
Objeto |
|
Opcional |
|
||
|
|
session_id |
ID de la sesión. |
String |
"a68653f7-2310-40af-a7f2-43065" |
Opcional |
|
|
|
|
payer |
Objeto con la información del comprador para el pago. |
Objeto |
|
Opcional |
|
|
|
|
|
name |
Nombre del cliente que realiza la transacción. |
String |
“Dong” |
Opcional |
|
|
|
|
|
Correo electrónico del cliente que realiza la transacción. |
String |
"buyer @email.com" |
Opcional |
|
|
|
|
phone |
Número telefónico del cliente que realiza la transacción. |
String |
“55555555” |
Opcional |
|
|
|
shipping_address |
Objeto con la dirección de envío. |
Objeto |
|
Opcional |
|
|
|
|
|
postal_code |
Código postal. |
String |
“03800” |
Opcional |
|
|
|
|
street |
Nombre de la calle. |
String |
“Av Uno” |
Opcional |
|
|
|
|
number |
Número exterior del domicilio. |
String |
“104” |
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. |
String |
"clip.mx" |
Opcional |
Sitio web del comercio donde el comprador está realizando el pago. |
|
Respuesta
La respuesta contiene todos los elementos enviados en el body más los campos que se muestran en la siguiente tabla:
|
Parámetro |
Descripción |
Tipo |
Notas |
||
|
id |
Número de identificación de la transacción. |
String |
Formato: UUID |
||
|
amount_refunded |
Cantidad reembolsada. |
Float |
En caso de existir un reembolso asociado con esta transacción se mostraría en este campo. |
||
|
installment_amount |
Monto de cada mensualidad. |
Float |
|
||
|
net_amount |
Monto cobrado sin incluir propina. |
Float |
Contiene máximo 2 decimales. |
||
|
paid_amount |
Monto cobrado incluyendo propinas. |
Float |
Contiene máximo 2 decimales. |
||
|
paid_amount |
Monto final transaccionado. |
Float |
Contiene máximo 2 decimales. |
||
|
payment_method |
Objeto con el método de pago utilizado para completar la transacción |
Objeto |
|
||
|
|
id |
Número de identificación |
String |
|
|
|
|
token |
Token ID de la tarjeta |
String |
El token que se genera por medio del endpoint de Card token |
|
|
|
type |
Tipo |
String |
|
|
|
|
card |
Objeto con la información de la tarjeta |
Objeto |
|
|
|
|
|
bin |
Número BIN |
String |
|
|
|
|
issuer |
Banco emisor |
String |
|
|
|
|
name |
Nombre en la tarjeta |
String |
|
|
|
|
country |
País |
String |
|
|
|
|
last_digits |
Últimos 4 dígitos del tarjeta |
String |
|
|
|
|
exp_year |
Año de expiración |
String |
|
|
|
|
exp_month |
Mes de expiración |
String |
|
|
receipt_no |
Número de recibo. |
String |
|
||
|
refunds |
Array con los reembolsos asociados a este pago |
Array |
|
||
|
status |
Estado del pago |
String |
|
||
|
status_detail |
Detalle del estado del pago |
Objeto |
|
||
|
|
code |
Código de estado |
String |
|
|
|
|
message |
Descripción del estado |
String |
|
|
|
pending_action |
Objeto de validación 3DS |
Objeto |
|
||
|
|
type |
Tipo de acción pendiente para validar |
String |
Único posible valor es “open_modal” |
|
|
|
url |
URL para realizar la validación 3DS |
String |
Contiene la URL a la cuál debes redirigir al cliente para hacer la validación 3DS. |
|
|
created_at |
Fecha de creación. |
String |
Formato ISO 8601 ( YYYY-MM-DDTHH-MM-SSZ). |
||
|
approved_at |
Fecha de aprobación del pago. |
String |
Formato ISO 8601 ( YYYY-MM-DDTHH-MM-SSZ). |
||
Código de ejemplo
Ejemplo de una llamada.
El siguiente bloque de código muestra un ejemplo de la solicitud cURL:
curl --location 'https://api.payclip.com/payments' \
--header 'Authorization: Basic MTBkMTA2Y2QtMTI4Ny00MjI1LWE0ZWQtNzY3MWRkM2Y5ZDEzOjExNWYwMjE0LWJkZDgtNGY1ZS04ODRmLWVhMTM0YjVhNTUyNA==' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": 0.01,
"currency": "MXN",
"description": "Test Transparent Checkout API",
"payment_method": {
"token": "0915e7-f6f-862-89e-0c5d71ae6"
},
"customer": {
"email": "[email protected]",
"phone": "5555555555"
}
}'
Ejemplo de un objeto de la respuesta
El siguiente objeto es una respuesta de éxito con código HTTP 201 OK:
{
"id": "3d62e0-57a8-d22-a90-d59e0d94f",
"amount": 0.01,
"tip_amount": 0,
"amount_refunded": 0,
"installment_amount": 0.01,
"installments": 1,
"capture_method": "automatic",
"net_amount": 0.01,
"paid_amount": 0.01,
"captured_amount": 0.01,
"binary_mode": false,
"approved_at": "2024-02-27T04:14:50.868762942Z",
"country": "MX",
"currency": "MXN",
"description": "Test Transparent Checkout API",
"external_reference": "",
"customer": {
"address": {
"city": "Benito Juárez",
"country": "México",
"colony": "San Pedro de los pinos",
"number": "118",
"postal_code": "03800",
"state": "ciudad de México",
"street": "Av Uno"
},
"description": "Descripción",
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"identification": {
"id": "INE",
"type":"123456"
},
"phone": "5555555555",
},
"payment_method": {
"id": "master",
"type": "credit_card",
"card": {
"bin": "555555",
"issuer": "SANTANDER PR",
"name": "John Doe Doe",
"country": "MX",
"last_digits": "2222",
"exp_year": "99",
"exp_month": "12"
},
"token": "0915e7-f6f-862-89e-0c5d71ae6"
},
"pending_action": {},
"receipt_no": "SzWn",
"refunds": [],
"statement_descriptor": "",
"status": "approved",
"status_detail": {
"code": "AP-PAI01",
"message": "paid"
},
"metadata": {},
"return_url": "",
"webhook_url": "",
"created_at": "2024-02-27T04:14:49.687206862Z",
"version": 0
}
STATUS Y STATUS_DETAIL
Al realizar un pago a través del endpoint de POST/payments reibirás los siguientes parámetros:
"status": "approved",
"status_detail": {
"code": "AP-PAI01",
"message": "paid"
}
En el parámetro “status” encontrarás el estado del pago. Los posibles valores son los siguientes:
- Approved: El pago fue aprobado.
- Refunded: El pago fue reembolsado.
- Cancelled: El pago no prospero desde un estado pendiente o autorizado.
- Rejected: El pago fue rechazado.
- Authorized: El pago fue autorizado pero no se ha hecho el cargo.
- Pending: El pago quedó pendiente de una acción a realizar para que prospere. Ej. Falta la autenticación 3DS.
Dentro del objeto “status_detail” podrás encontrar un código y un mensaje proporcionando más detalles acerca del status del pago.
A continuación se muestra una tabla con todos los posibles códigos y mensajes posibles:
|
Status |
Code |
Message |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Autenticación 3DS
Cuando un cargo requiere la autenticación 3DS, el parámetro de respuesta "pending_action" tendrá una URL; esta URL te servirá para redirigir a tus clientes para realizar la autenticación.
"pending_action": {
"type": "open_modal",
"url": "https://3ds.payclip.com?transaction=a679"
}
Se debe tomar el parámetro {pending_action.url} y abrirlo dentro de un iFrame:
<iframe
className={styles.iframe}
title="cybersource3Ds"
src={pending_action.url}
data-testid="cybersource3Ds-iframe"
/>
Añadir el postMessage listener para conocer la respuesta de la autenticación:
window.addEventListener(
`message`,
async (event) => {
if (event.origin === process.env.NEXT_PUBLIC_CYBERSOURCE_DOMAIN) {
const paymentId = event.data?.paymentId;
if (paymentId) {
executePolling(paymentId);
} else {
notifyPaymentIdNotProvided();
}
}
},
false,
);
Siempre se debe evaluar: If event.origin = CYBERSOURCE_DOMAIN (https://3ds.payclip.com)
Para mayor información, consultar esta documentación mencionada en “Step 4: Step-Up IFrame” (Pág. 38).
Códigos de respuesta
La siguiente tabla contiene una lista de los códigos de respuesta y su asociación con algunos de los estados HTTP:
|
Estado HTTP |
Error code |
Mensaje |
|
|
400 |
CL1307 |
card token not found |
|
|
400 |
CL1310 |
installment not found or invalid |
|
|
400 |
CL1600 |
Corrupted data: invalid emv amout, QPS international, invalid terminal country |
|
|
400 |
CL1607 |
card token expired |
|
|
400 |
CL2200 |
Input validation |
|
|
400 |
CL2221 |
Invalid card holder verification method |
|
|
400 |
CL1125 |
Valera not allowed for this merchant |
|
|
401 |
CL1501 |
Unauthorized |
|
|
500 |
AI1899 |
Internal error. |
|
Este es un ejemplo del objeto de error en formato JSON:
{
"error_code": "CL1310",
"message": "Bad Request",
"detail": [
"installment not found or invalid"
]
}
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 recomiendan las siguientes 2 consideraciones:
- Parámetro customer_information: Enviar información relacionado al cliente quien realiza el pago.
- Script Clip: Incluir un Script Javascript en la pasarela de pagos.
Parámetro customer
Se recomienda enviar la información del customer para un mejor análisis de riesgo:
"customer": {
"first_name": "Dong",
"last_name": "Lee",
"email": "[email protected]",
"phone": "55555555"
,"address": {
"postal_code": "1234567",
"street": "AnyStreet",
"number": "12456",
"city": "Benito Juárez",
"colony": "Ejidos de Cambray",
"country": "México",
"state": "Ciudad de México"
},
"description": "product manager",
"identification": {
"id": "TE02CSXRS01",
"type": "CURP"
}
}
Script Clip
Clip requiere información adicional para identificar al comprador. El siguiente Script nos permite identificarlo:
<script id="cybersource" src="https://h.online-metrix.net/fp/tags.js?org_id=1snn5n9w&session_id=clip_mx${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}: 7376d6ec-e9f6-48d5-a1ce-26241bd7e5d7
<script id="cybersource" src="https://h.online-metrix.net/fp/tags.js?org_id=1snn5n9w&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
Notificaciones Webhook
Si se deseas recibir notificaciones webhook en tiempo real, es necesario tomar en cuenta las siguientes consideraciones:
- Contar con un servicio para escuchar Webhook notification del comercio
- Realizae una llamada a el endpoint GET /payments/{payment_id} de Clip
Para recibir las webhook notifications, es necesario compartir la Webhook URL cuando se consume el servicio POST /payments bajo el siguiente parámetro:
{
"webhook_url": "https://us1.make.com/64555/hooks/129782/queue/a1cb5be30d510dee6111e2386ceab85f"
}
Al consumir el servicio POST /payments, el mensaje dentro de la notificación webhook que recibirás se verá de la siguiente manera:
{
"id": "cfd8760c-9eae-47dc-8a83-ec643bb39034"
}
Donde el parámetro “id” corresponde a ID del pago o Payment_id. Dicho valor de ID de pago debe ser consultado con la API de GET /Payments/{payment_id}.
Estarás recibiendo notificaciones webhook cuando se intente un pago, sin importar si es declinado, rechazado, pagado u otro estatus de pago.
Llamada de prueba
Puedes realizar una llamada de prueba llenando los campos necesarios en el formulario que se muestra a continuación.
Asegúrate de poner tu token de autenticación en el campo "Header: Autorization" del widget localizado a tu derecha:
Por último dale click en el botón "Try It!":
