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
	email		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.
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": "correo@ejemplo.com",
        "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": "correo@ejemplo.com",
        "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

approved

AP-PAI01

Paid

approved

AP-REF01

Partially refunded

refunded

RE-REF01

Refunded

authorized

AU-CAP01

Pending capture

cancelled

CA-AUT01

Cancelled

cancelled

CA-MAN01

Cancelled

cancelled

CA-MER01

Cancelled

rejected

RE-BIN01

Rejected

rejected

RE-ERI03

Rejected

rejected

RE-3DS01

Fail 3DS authentication

rejected

RE-CHI01

Rejected

rejected

RE-ISS01

Not sufficient funds

rejected

RE-ISS02

Do not honor

rejected

RE-ISS03

Restricted card

rejected

RE-ISS04

Reserved for private use

rejected

RE-ISS05

Transaction not permitted to cardholder

rejected

RE-ISS06

Pick-up card

rejected

RE-ISS07

Expired card

rejected

RE-ISS08

Exceeds withdrawal amount limit

rejected

RE-ISS09

Invaliad pin (one time)

rejected

RE-ISS10

Allowable number of pin tries exceeded

rejected

RE-ISS11

Refer to card issuer

rejected

RE-ISS12

Invalid amount

rejected

RE-ISS13

Destination not available (Issuer offline)

rejected

RE-ISS14

Issuer or switch is inoperative

rejected

RE-ISS15

Visa/mc fallback

rejected

RE-ISS16

Invalid card number (no such number)

rejected

RE-ISS17

Invalid merchant

rejected

RE-ISS18

Invalid transaction

rejected

RE-ISS19

Rejected

rejected

RE-ISS20

Rejected

rejected

RE-ISS99

Generic error

rejected

RE-ERI05

KYC not completed

pending

PE-EMV01

Waiting emv

pending

PE-SIG01

Waiting signature

pending

PE-3DS01

Waiting 3DS

pending

PE-TIC01

Waiting payment

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!":

Realiza una llamada de prueba: