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.
Para poder consumir este endpoint necesitas verificar tu identidad con Clip. Puedes encontrar más información sobre cómo verificar tu identidad aquí.
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 en donde manual es para realizar únicamente la autorización sin hacer el cargo. 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 |
"9144b8-e4cb-4e14-8412-d2b4d89" |
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 |
Pagos diferidos. Pueden ser meses sin intereses si los tienes activados, o meses con intereses, en caso de que tengas desactivados los MSI. |
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. Para diferenciar MSI de MCI compara la suma del amout+tip con el paid amount, si es igual entonces son MSI, de lo contrario son MCI. |
||
|
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 |
|
|
|
exterior _number |
Número exterior del domicilio. |
String |
"104" |
Opcional |
Para AMEX este campo es obligatorio Este campo es retro compatible con el nombre "number" |
|
|
|
interior _number |
Número interior del domicilio. |
String |
"Depto 11" |
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 |
|
|
|
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. |
||
|
return_url |
URL para redirigir a tus clientes en caso de que el pago sea exitoso. |
String |
"www.url.com" |
Opcional |
|
||
|
binary_mode |
Te permite rechazar automáticamente las transacciones que requieran validación 3DS. |
Boolean |
true |
Opcional |
Si es "true" y se requiere validación 3DS, se rechazará en automático. |
||
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. |
||
|
authorized_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 MTBkMTA2Y2QtMTOjExNWYwMjE0LWJkZDgtNGY1ZS04ODRmLWVhMTM0YjVhNTUyNA==' \
--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",
"external_number": "118",
"internal_number": "Depto 11",
"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": "123456",
"type":"INE"
},
"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",
"return_url":"www.yoursite.com",
"version": 0
}
STATUS Y STATUS_DETAIL
Al realizar un pago a través del endpoint de POST/payments recibirá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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
|
|
409 |
CL1620 |
Conflict.This payment was previously received. |
|
|
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"
]
}
Llamada de prueba
Puedes realizar una llamada de prueba llenando los campos necesarios en el formulario que se muestra abajo.
Asegúrate de poner tu token de autenticación en el campo "Header: Autorization" del widget localizado a tu derecha, y dale click en el botón "Try It!":
