Introducción a Checkout Clip v1

Checkout 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.

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 aceptamos pesos mexicanos “MXN”

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

failure

URL a la que se redireccionará al cliente cuando han fallado varios intentos.

String

default

URL de la tienda virtual.

String

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 menor a las 23:59:59 horas (UTC) del mismo dia 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 me_reference_id  y customer_info  se muestran como ejemplo.

me_reference_id

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.

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

zip_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.

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_code

ID de la solicitud de pago

String

expired_at

Indica la fecha y hora de expiración del enlace de pago.

String

Formato ISO 8601 ( YYYY-MM-DDTHH-MM-SSZ )

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.

payment_method

Métodos de pago aceptados en el link de pago.

String

Este elemento  es opcional  
Los valores aceptados son ["CARD","CASH"].
 

["CARD"] te permite aceptar únicamente tarjeta.
 

["CASH"] te permite aceptar únicamente efectivo.
 

En caso de no especificarlo se mostrará el valor por default, el cual contiene ambos métodos de pago.

enable_tip

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.

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.

currency

Objeto que contiene la información del tipo de moneda.

Objeto

Este elemento  es opcional

show_currency_code

Muestra u oculta el tipo de moneda.

Boolean

Este elemento  es opcional  
El tipo de moneda es MXN.
 
Si es true se mostrarán el tipo de moneda.
 
Si es false se ocultará el tipo de moneda.
 
El valor por default es false.

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:

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

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

{
  "payment_request_id": "2cbf5775-1cdd-4601-9712-c4a6ab7fa6f5",
  "object_type": "payment_link",
  "status": "CHECKOUT_CREATED",
  "last_status_message": "Payment Request is active",
  "amount": 100.25,
  "receipt_no": "EyCtYWF",
  "currency": "MXN",
  "purchase_description": "Backpack's sale",
  "redirect_url": {
     "success": "https://my-website.com/redirection/success",
     "error": "https://my-website.com/redirection/error",
     "default": "https://my-website.com/redirection/default",
  },
  
  "metadata": {
     "me_reference_id": "OID123456789",
     "customer_info": {
        "name": "Alejandro Lee",
        "email": "[email protected]",
        "phone": "5512345678"
     },    
    "billing_address": {
      "zip_code": "03800",
      "locality": "San Pedro",
      "city": "Benito Juárez",
      "country": "México",
      "state": "Ciudad de México",
      "street": "Av Uno",
      "outdoor_number": "104",
      "interior_number": "A203",
      "reference": "Edificio gris",
      "between_streets": "Entre calle 13 y calle 9",
      "floor": "2"    
 	 		}
   },
  "override_settings": {
    "payment_method": [
      "CARD",
      "CASH"
    ], 
    "locale": "en-US",
    "enable_tip": false,
    "currency": {
            "show_currency_code": false            
        }      
  },    
  
  "webhook_url": "https://hook.us1.make.com/k5f98kqxuuxgn4td6hgejrnu6lsi362p",
  "created_at": "2020-04-30T00:00:00.000Z",
  "modified_at": "2020-04-30T00:00:00.000Z",
  "payment_request_url": "https://completa-tu-pago.payclip.com/b7192811-6fa0-4038-b8dc-ad755dad1975",
  "expired_at": "2020-04-30T00:00:00.000Z",
  "payment_request_code": "TG7SBSMF",
  "qr_image_url": "https://clip.mx/qr/bee00b60-595f-4540-bdfc-b9d85eb00b5b"
}

Mensajes de error

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

Código HTTP

Mensaje

Código de mensaje

Detalle

400

Objeto no encontrado

001

Cuerpo de la solicitud vacío

400

Entrada inválida

002

Error de validación de formato

400

Entrada inválida

002

Error de validación del monto

400

Entrada inválida

002

Error de validación del campo "expires_at"

400

Campo inválido

003

Error de validación de contenido

400

Solicitud incorrecta

004

Error al crear payment_link

400

Método de pago inválido/Desconocido

005

El método de pago tiene un valor incorrecto

401

Error de autorización

011

Token de autenticación incorrecto

403

Prohibido

-

Solicitud bloqueada.Si tu sitio web está alojado en un servidor fuera de México o EUA, favor de contactar a Customer Happiness para recibir asistencia.

Ejemplo del mensaje de error

404

No encontrada

021

Página no encontrada

412

Límite de solicitudes alcanzado

031

Las siguientes son los motivos de excedentes del límite de solicitudes:

* Monto máximo por link de pago

* Número de links creados por día

* Max TPV acumulado por  link creado por día

500

Error de Servidor Interno

101

Hubo un error en la validación del payment_link.

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

{
  “message”: ”Solicitud incorrecta”, 
  “code_message”: ”004”,
  “detail”: “Error al crear payment_link”
}

Colección Postman

Descarga la colección Postman de los endopoints de la API de Checkout en el siguiente link.

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 [email protected].

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 [email protected]