Link de pago

Referencia técnica completa de los endpoints necesarios para generar y gestionar links de pago. Esta sección es la base tanto para la integración por Link de pago como para Checkout Elements.

Antes de usar estos endpoints asegúrate de haber completado el proceso de autenticación descrito en la sección Autenticación y seguridad.

Crear link de pago

Con tu token activo, crea la transacción. Tu servidor envía una solicitud POST a PayCode con todos los detalles del cobro: el monto, el producto, los métodos de pago que quieres ofrecer y la URL a la que regresará el usuario cuando termine de pagar. Método: POST Endpoint: /api/v2/links-pago/crear_link Header requerido: Authorization: Bearer <access_token> Cuerpo de la solicitud:

{
  "concept": "Producto",
  "require_info": 0,
  "customer_code": "",
  "type_link": "1",
  "expiration_time": {
    "days": 360,
    "hours": 0,
    "mins": 0,
    "secs": 0
  },
  "notifications": {
    "email": false,
    "sms": false
  },
  "payment_method": {
    "codi": true,
    "credit_card": true,
    "spei": true,
    "cash_in": true
  },
  "products": [
    {
      "amount": "10.1",
      "name": "Producto",
      "product_code": "seguro123",
      "quantity": 1
    }
  ],
  "redirect_url": "",
  "sms_text": "Hola #NOMBRE, Agradeceremos la liquidación de tu pago.",
  "style_configuration": {
    "background": "#5b7d99",
    "color_btn": "#5b7d99",
    "colortext_btn": "#FFFFFF"
  },
  "metadata": {
    "campo_1": "valor1",
    "campo_2": "valor2",
    "campo_3": "valor3"
  }
}

Descripción de los campos:

Campo	Descripción
`concept`	Descripción corta de la transacción
`require_info`	`1` solicita nombre, apellido, email y teléfono al cliente durante el checkout. `0` usa el `customer_code` de un cliente ya registrado
`customer_code`	Identificador único del cliente final. Puede dejarse vacío si `require_info` es `1`. Si el cliente ya pagó antes, el sistema le asigna el mismo código usando el email como referencia
`type_link`	`1` genera un link de uso único. `2` permite que el link se use múltiples veces, solo disponible cuando ha sido habilitado por un asesor de PayCode
`expiration_time`	Tiempo de vida del link. Una vez vencido el tiempo configurado el link deja de ser válido
`notifications`	Si `email` o `sms` es `true`, el sistema envía una notificación al cliente cuando la transacción se complete
`payment_method`	Define qué métodos de pago se muestran en el checkout. Los métodos deben estar previamente configurados por PayCode
`products`	Lista de productos de la transacción. Si no tienes `product_code` puedes usar `null`. Puedes incluir múltiples productos en la misma transacción
`redirect_url`	URL a la que el usuario será redirigido al terminar la transacción
`sms_text`	Contenido del mensaje SMS de notificación
`style_configuration`	Color de fondo, color del botón y color del texto del checkout
`metadata`	Campos adicionales que se incluirán en el payload del webhook. Se recomienda incluir al menos el `customer_code` para facilitar la conciliación

El retorno es un link con formato https://checkout.paycode.com.mx/<hash>. El hash al final es el identificador de la transacción, lo necesitas para los endpoints de obtener detalles y procesar el pago.

Obtener detalles del pago

Con el hash del paso anterior consultas los detalles de la transacción. La respuesta contiene toda la información que necesitas para construir la pantalla de checkout: datos del cliente, métodos de pago habilitados, productos y configuración visual. Método: POST Endpoint: /api/v2/link_pago/obtener_pago Header requerido: Authorization: Bearer <access_token> Cuerpo de la solicitud:

{
  "hash": "XNP-xxx-k1u"
}

Ejemplo de respuesta 200 OK:

{
  "success": true,
  "data": {
    "info": {
      "hash": "XNP-MRG-k1u",
      "base_url": "https://dev-checkout.paycode.com.mx/",
      "total": 0,
      "paid_at": null,
      "concept": "Pruebas Link de Pago api",
      "business": "PayCode",
      "limit_date": "2030-01-28 23:59:59",
      "redirect_url": "https://paycode.com.mx/",
      "is_expired": 0,
      "require_information_customer": 0,
      "client": {
        "first_name": "Jose",
        "paternal_surname": "Fernandez",
        "maternal_surname": "Atínez",
        "customerPhone": "557412345",
        "customerEmail": "jose@gmail.com",
        "full_name": "Jose Fernandez Atínez",
        "tokens": [
          {
            "id": 21,
            "brand": "VISA",
            "card": "4241",
            "card_holder_name": "jose Fernandez"
          }
        ]
      },
      "payments": {
        "codi": 1,
        "spei": 1,
        "credit_card": 1,
        "cash_in": 0
      },
      "config_link": {
        "logo": "https://s3.us-east-2.amazonaws.com/...",
        "background": "#FFFFFF",
        "background_btn": "#000000",
        "color_btn_text": "#FFFFFF",
        "thanks_text": "Gracias por tu compra."
      },
      "products": [
        {
          "id": 8055,
          "name": "League City",
          "amount": 1,
          "quantity": 0
        }
      ],
      "tokenizable": true
    }
  }
}

Usa esta respuesta para construir el formulario de pago. Los campos que debes solicitar al cliente dependen del valor de require_information_customer con el que se creó el link.

Procesar el pago

Con los datos del cliente capturados en tu formulario, envía la información al endpoint del método de pago elegido. Método: POST Endpoint: /api/v2/pagos/pago_tarjeta Header requerido: Authorization: Bearer <access_token> Cuerpo de la solicitud ejemplo con tarjeta de crédito:

{
  "hash": "XNP-xxx-k1u",
  "numero_tel": "",
  "payment_amount": 1,
  "products": [
    {
      "amount": 1,
      "id_product": 1,
      "name": "Seguro de gastos médicos",
      "quantity": 1
    }
  ],
  "info": {
    "card": "4242 4242 4242 4242",
    "expiry": "12/34",
    "year": "34",
    "month": "12",
    "code": "123",
    "name_card": "Pedro Ramirez"
  },
  "dinamic_fields": [],
  "paycips": true
}

Cada método de pago tiene su propio endpoint. El ejemplo anterior corresponde a tarjeta de crédito. Los endpoints para SPEI, CoDi y efectivo siguen la misma estructura pero con los campos específicos de cada método.

Redirección

Una vez que recibes la respuesta del procesador de pago usa el redirect_url que configuraste al crear el link para enviar al usuario a la pantalla de confirmación. Si el pago fue exitoso el usuario verá la página de éxito de tu sitio. Si fue rechazado puedes redirigirlo a una página de error o reintento según la lógica de tu aplicación.

COMIENZA AQUÍ

INTEGRACIONES FRONTEND

INTEGRACIONES BACKEND V2

CASOS DE USO

Crear link de pago

Obtener detalles del pago

Procesar el pago

Redirección

​Crear link de pago

​Obtener detalles del pago

​Procesar el pago

​Redirección

Crear link de pago

Obtener detalles del pago

Procesar el pago

Redirección