La API de Checkout Redireccionado de Clip te ayuda a integrar una solución de pago segura a tu tienda en línea. Cuando tus clientes estén listos para pagar, serán redirigidos a un sitio de pago en línea generado por tu tienda en línea a través de la API de Checkout.

El siguiente diagrama muestra cómo funciona la API de Checkout al integrarla a tu tienda en línea:

1590 — Diagrama de integración de Checkout Clip a tu tienda en línea.

🚧
Importante
Para poder integrar la API de Checkout en tu ecommerce necesitas verificar tu identidad con Clip. Puedes encontrar más información sobre cómo verificar tu identidad aquí.

Objeto Completo

Ya sea que hayas generado un nuevo link de pago o estés revisando el estado de un link de pago generado previamente, la siguiente tabla describe los elementos del objeto de respuesta completo que recibirá tu sistema:

Elemento			Descripción	Tipo	Notas
payment_request_id			Identificador del link de pago.	String	Formato UUID. Longitud máxima 36 caracteres. Se genera un nuevo payment_request_id en cada solicitud para Crear un nuevo link de pago
object_type			Valor estático del link de pago “payment_request”.	String	Valor fijo
status			Estado actual del link de pago.	String	Los estados posibles son: CHECKOUT_CREATED: El link de pago fue creado exitosamente. CHECKOUT_PENDING: El link de pago tuvo un intento de pago y se encuentra activo. CHECKOUT_CANCELLED: El link de pago fue cancelado por exceso de intentos (máximo 5). CHECKOUT_EXPIRED: El link de pago expiró. El link de pago expira después de 72 horas. CHECKOUT_COMPLETED:El link de pago se liquidó.
last_status_message			Mensaje del último estado del link de pago dependiendo del elemento status.	String
amount			Número con decimales que representa el monto a cobrar.	Float	El número mínimo entero es 1. Utilizar dos decimales. Para representar 50 pesos y 50 centavos el valor del parámetro amount sería ‘50.50’ En caso de que el monto contenga más de dos decimales se redondea con el siguiente criterio: Menor a #.##5 se redondea hacia abajo. Ejemplo: ’500.22499899’ se redondea a ’500.22’ Mayor o igual a #.##5 se redondea hacia arriba. Ejemplo: ’500.225121231’ se redondea a ’500.23’
receipt_no			Identificador de la transacción, se mostrará en el evoucher de la transacción.	String	Este campo se muestra cuando el valor de status es CHECKOUT_COMPLETED
currency			Código de tres caracteres representando la moneda.	String	Formato ISO 4217 (Mayúsculas). Nota: Por el momento, solo se aceptan pesos mexicanos “MXN” y dólares “USD”
purchase_description			Texto describiendo el cargo.	String	Formato UTF-8 Se aceptan los siguientes caracteres especiales ~!@#$%^&*()\=+\\\|\[{\]};:'"<>/? No se aceptan emojis. Longitud mínima: 1 Longitud máxima: 255
redirection_url			Objeto con las URLs para redirección del cliente después del pago.	Objeto
	success		URL a la que se redireccionará al cliente cuando el pago es exitoso.	String
	error		URL a la que se redireccionará al cliente cuando han fallado 5 intentos.	String
	default		URL de la tienda virtual.	String
override_settings			Objeto que el servicio solicitante puede utilizar para cambiar la configuración por default del Checkout.	Objeto	Este objeto es opcional Permite sobreescribir la configuración de los parámetros por defecto del Checkout.
	locale		Seleccionador de lenguaje: es-MX (español) o en-US (inglés).	String	Longitud máxima 85 caracteres. El valor default es es-MX. Este parámetro es opcional, si no se envía en la solicitud se utiliza el valor default. Acepta mayúsculas y minúsculas.
	tip_enabled		Muestra u oculta las propinas.	Boolean	Este elemento es opcional Si enabled: true se mostrarán las propinas. Si enabled: false se ocultarán las propinas.
	merchant_info		Objeto para mostrar la información del comercio en el checkout.	Objeto
		show_contact_info	Permite mostrar u ocultar la información de contacto de tu negocio en el checkout.	Boolean	Permite mostrar u ocultar la información de contacto de tu negocio en el checkout.
expires_at			Indica la fecha y hora de expiración de la solicitud de pago. Tiene que ser mayor a 00:01:00 minuto y máximo 365 días a partir del día de creación de la solicitud.	String	Este objeto es opcional Formato ISO 8601 ( YYYY-MM-DDTHH-MM-SSZ). Su valor default es tres días
metadata			Objeto que el servicio solicitante puede utilizar para identificar la intención de pago.	Objeto	Formato JSON El conjunto de parejas llave:valor lo puede definir el desarrollador. Este objeto es opcional , los elementos external_reference y customer_info se muestran como ejemplo.
	external_reference		ID de referencia de la orden para rastrear las transacciones.	String	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. Este elemento es opcional y es un ejemplo de lo que puedes incluir dentro del objeto metadata.
	customer_info		Objeto con la información del cliente para el link de pago.	Objeto	Este objeto es opcional Si se incluye se mostrará en el Checkout.
		name	Nombre del cliente que realiza la transacción.	String	Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		email	Correo electrónico del cliente que realiza la transacción.	String	Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		phone	Número telefónico del cliente que realiza la transacción.	Number	Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
	shipping_address		Objeto con la dirección de envióo.	Objeto	Este objeto es opcional Solo aplica para pagos con AMEX. Si se incluye se mostrará pre-llenado en el Checkout. No es necesario mandar toda la dirección, se pueden mandar solo los campos necesarios. Si el código postal no existe, ese campo se dejará en blanco
		postal_code	Código postal.	String	Longitud máxima: 10 caracteres. Caracteres especiales permitidos: Guión medio (-) y punto (.). Se permiten caracteres alfanuméricos [0-9] [a-Z] . Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		locality	Colonia.	String	Longitud máxima: 255 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacio ( ). Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		city	Delegación o municipio.	String	Longitud máxima: 255 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Se permiten acentos. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		state	Estado.	String	Longitud máxima: 255 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		country	País.	String	Longitud máxima: 255 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		street	Nombre de la calle.	String	Longitud máxima: 255 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		outdoor_number	Número exterior del domicilio.	String	Longitud máxima: 10 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		interior_number	Número interior del domicilio.	String	Longitud máxima: 10 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		reference	Referencia del domicilio.	String	Longitud máxima: 255 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		between_streets	Entre calles que rodean al domicilio.	String	Longitud máxima: 255 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		floor	Número de piso del domicilio.	String	Longitud máxima: 10 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
	billing_address		Objeto con la dirección de facturación.	Objeto	Este objeto es opcional Solo aplica para pagos con AMEX. Si se incluye se mostrará pre-llenado en el Checkout. No es necesario mandar toda la dirección, se pueden mandar solo los campos necesarios. Si el código postal no existe, ese campo se dejará en blanco
		postal_code	Código postal.	String	Longitud máxima: 10 caracteres. Caracteres especiales permitidos: Guión medio (-) y punto (.). Se permiten caracteres alfanuméricos [0-9] [a-Z] . Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		locality	Colonia.	String	Longitud máxima: 255 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacio ( ). Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		city	Delegación o municipio.	String	Longitud máxima: 255 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Se permiten acentos. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		state	Estado.	String	Longitud máxima: 255 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		country	País.	String	Longitud máxima: 255 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		street	Nombre de la calle.	String	Longitud máxima: 255 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		outdoor_number	Número exterior del domicilio.	String	Longitud máxima: 10 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		interior_number	Número interior del domicilio.	String	Longitud máxima: 10 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		reference	Referencia del domicilio.	String	Longitud máxima: 255 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		between_streets	Entre calles que rodean al domicilio.	String	Longitud máxima: 255 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
		floor	Número de piso del domicilio.	String	Longitud máxima: 10 caracteres. Caracteres especiales permitidos: Guión medio (-) y espacios. Este elemento es opcional Si se incluye se mostrará pre-llenado en el Checkout.
custom_payment_options			Objeto con la configuración de los meótodos de pago aceptados.	Objeto
	international_enabled		Te permite aceptar tarjetas internacionales o rechazarlas en automático.	Boolean	Para aceptar tarjetas internacionales, deberás antes verificar tu identidad, de lo contrario aunque mandes este campo en “true” es probable que sean rechazadas.
	installments_msi		Te permite configurar cuántos meses sin intereses quieres aceptar para la transacción.	Int array	Posibles valores: 3, 6, 9,12,18, y 24. Tienes que configurar los MSI desde tu app o dashboard. Se envía de esta forma:"installments_msi": [3,9]
	payment_method_brands		Te permite configurar las marcas de tarjetas que quieres aceptar.	String array	Valores permitidos: visa\|mastercard\|amex\|carnet\|discover\|diners. Se envía de esta forma:"payment_method_brands": ["visa","mastercard"]
	payment_method_types		Te permite configurar los métodos de pago aceptados.	String array	Valores permitidos: debit, credit, cash. Se envía de la siguiente forma: "payment_method_types": ["debit","credit","cash"] . Al incluir el valor `"cash"`, se podrá elegir pagar con OXXO®, consulta la documentación completa sobre pagos con OXXO®
prevention_data			Objeto con la información para prevención de riesgo	Objeto
	submerchant_id		Identificador del subcomercio o vertical de negocio	String	Este parámetro es opcional y es un ejemplo de lo que puedes incluir para clasificar transacciones
created_at			Indica la fecha y hora de creación del enlace de pago.	String	Formato ISO 8601 ( YYYY-MM-DDTHH-MM-SSZ )
modified_at			Indica la fecha y hora de modificación del enlace de pago.	String	Formato ISO 8601 ( YYYY-MM-DDTHH-MM-SSZ )
payment_request_url			Link de pago a donde se redirigirá al cliente.	String
payment_request_id			ID de la solicitud de pago	String
webhook_url			URL del endpoint que recibirá notificaciones webhook del link de pago.	String	Puedes consultar la estructura de la notificación webhook en el siguiente link
qr_image_url			URL del código QR del link de pago que podrá ser escaneado por tu cliente.	String

^*La API de Checkout de Clip tiene cuatro factores de prioridad para determinar el idioma de la página de pago:

El idioma elegido por el usuario.
El campo locale en override_settings.
El idioma del navegador.
El idioma predeterminado: es-MX.

El objeto completo en formato JSON se muestra a continuación:

{ 
    "amount": 500,
    "currency": "MXN",
    "purchase_description": "Hamburguesas 2x1 + 50% descuento & envío gratis",
    "redirection_url": {
        "success": "https://www.clip.mx/success",
        "error": "https://www.clip.mx/error",
        "default": "https://merchant_ecoomerce.com"
    },
    "override_settings": {
        "locale": "es-MX",
        "tip_enabled": true,

        "merchant_info": {
            "show_contact_info": true
        }
    },
    "expires_at": "2024-10-26T13:17:00Z",
    "metadata": {
        "external_reference": "HXO-000-043",
        "customer_info": {
            "name": "Buyer Name",
            "email": "buyer@email.com",
            "phone": 5512345678,
            "matricula": "XXXX2"
        },
        "shipping_address": {
            "postal_code": "05200",
            "street": "Héctor Victoria",
            "outdoor_number": "54",
            "interior_number": "Villa Hermosa 123",
            "locality": "San José de los Cedros",
            "city": "Cuajimalpa de Morelos",
            "state": "Ciudad de México",
            "country": "mx",
            "reference": "Portón negro",
            "between_streets": "Entre calle 1 y calle 3",
            "floor": "1"
        },
        "billing_address": {
            "postal_code": 5200,
            "street": "Héctor Victoria",
            "outdoor_number": "54",
            "interior_number": "Villa Herm",
            "locality": "San José de los Cedros",
            "city": "Cuajimalpa de Morelos",
            "state": "Ciudad de México",
            "country": "mx",
            "reference": "Portón negro",
            "between_streets": "Entre calle 1 y calle 3",
            "floor": "1"
        }
    },
    "custom_payment_options": {
        "international_enabled": true,
        "installments_msi": [
            3,
            9
        ],
        "payment_method_brands": [
            "visa",
            "mastercard",
            "amex",
            "carnet",
            "discover",
            "diners",
            
        ],
        "payment_method_types": [
            "debit",
            "credit",
            "cash",
           
        ]      
    },  
    "prevention_data": {        
        "submerchant_id":"id 001"
    }
  
    "payment_request_id": "f3e8c27d-abc6-43c2-a0f1-e66c3cbc8ae6",
    "object_type": "payment_link",
    "status": "CHECKOUT_CREATED",
    "last_status_message": "Payment Request created successfully",
    "created_at": "2024-08-06T18:40:36Z",
    "payment_request_url": "https://dev-pago.payclip.com/f3e8c27d-abc6-43c2-a0f1-e66c3cbc8ae6",
    "modified_at": "2024-08-06T18:40:36Z",
    "expires_at": "2024-10-26T13:17:00Z",
    "qr_image_url": "https://qr.payclip.com/77921b07-03d7-4b7d-ae70-177cb696da51b"

}

Mensajes de error

La siguiente tabla detalla los mensajes de error para la API de Checkout Clip

Código HTTP	Error code	Message	Detail
400	001	Object not found	Missing request
400	002	Invalid input	Format validation error
400	002	Invalid input	Amount format validation error
400	002	Invalid input	Expires_at format validation error
400	002	Invalid input	Redirection URL Success format validation error
400	002	Invalid input	Redirection URL Error format validation error
400	002	Invalid input	Redirection URL Default format validation error
400	002	Invalid input	Customer email format validation error
400	002	Invalid input	Empty value is not allowed in installments_msi
400	002	Invalid input	Empty value is not allowed in payment_method_types
400	002	Invalid input	Empty value is not allowed in payment_method_brands
400	002	Invalid input	Invalid option in installments_msi, allowed values are 3\|6\|9\|12\|18\|24
400	003	Invalid field	Content validation error
400	004	Bad request	Error creating payment_link
400	005	Payment Method Invalid	Unknown payment method
400	010	Amount error	Amount doesn´t match with the item prices
400	011	Shipping cost error	Shipping cost doesn´t match with the item prices
400	040	Invalid input	Invalid installments_msi attribute to payment_method_types
400	041	Invalid input	Invalid option in payment_method_brands
400	042	Invalid input	Invalid international_enabled attribute to payment_method_types
400	044	Invalid input	Invalid request on payment method types for USD currency
400	045	Invalid input	Invalid request on payment method brands for USD currency
400	050	Invalid input	Invalid brand acceptance
400	060	Invalid input	Invalid type acceptance
400	070	Invalid input	Invalid international card acceptance
400	071	Invalid input	Invalid minimum amount to accept international card
400	072	Invalid input	Invalid maximum amount to accept international card
400	080	Invalid input	Account inactivated or suspended
401	011	Authorization error	The authorization token is incorrect
403		Request blocked	Please, contact to Customer Happiness
403	103	Forbidden	Unable to perform operation
404	021	Not found	Payment Request ID doesn´t exist
412	031	Max limit requested reached	Limit exceeded reason
500	101	Internal server error	Something went wrong with payment_link validation
502	111	Bad Gateway	Please, contact to Customer Happiness
503	121	Service Unavailable	Please, try again later
504	131	Gateway Timeout	Please, try again later

Este es un ejemplo del objeto de error en formato JSON:

{
"error_code": "002",
"message": "Invalid input",
"detail": [
  "Format validation error"
  ]
}

Incorpora el botón Clip

Completa el proceso usando nuestros botones y comunica a tus clientes que cobras con Clip.

En distintos formatos visuales
Adaptables a cada tamaño de pantalla
Con varios estilos para cada contexto de uso

Conocer botones Clip.

📘
¿Necesitas Ayuda?
Consulta las preguntas frecuentes y guías de solución de problemas de nuestro centro de soporte a desarrolladores .
Si lo que buscas no está documentado, contáctanos por alguno de los siguientes medios:

Activa el botón de Ayuda y llena el formulario. No olvides proporcionar un correo electrónico y tus dudas para que podamos asistirte de manera eficiente.

Publica tu pregunta en nuestro Foro. Publicar en el foro puede ayudar a otros desarrolladores que están experimentando el mismo problema.

Envía un correo electrónico a la dirección soporte-checkout@clip.mx.

O comunícate con nuestra área de Customer Happiness:

Llámanos al 55 6393-2323, Clip es el único con atención personalizada 24/7 los 365 días del año.

Envíanos un mensaje por WhatsApp al 55 6393-2323.

Escríbenos al correo help@clip.mx

Continuar leyendo

Continuar leyendo