Documentación para Desarrolladores

Integración de Pagos

Bienvenido a la guía oficial de integración de Frqtal Links. Con nuestra tecnología, puedes generar experiencias de pago dinámicas y adaptadas a tu identidad visual directamente en tu aplicación, personalizando colores y estilos básicos para una integración cohesiva.

Objetivo: Consumir nuestros endpoints para generar links de pago y checkouts inyectables de forma segura.

Guía de 3 pasos

Sigue este flujo simple para habilitar pagos en tu sistema:

1

Generar Credencial

Accede a tu Dashboard y crea una nueva credencial de integración. Esto te proporcionará una API Key única.

2

Configurar Backend

Implementa la llamada a nuestra API desde tu servidor utilizando la cabecera personalizada de autenticación.

3

Inyectar Checkout

Recibe el fragmento HTML de nuestra API e inyéctalo en tu frontend. ¡Listo para recibir pagos!

Autenticación

Todas las solicitudes a la API de integración deben realizarse a través de tu servidor (Backend) para proteger tus credenciales.

Debes incluir el token generado en cada petición usando la cabecera HTTP personalizada:

identity-frq-token-p: TU_API_TOKEN_AQUÍ

Nota: Nunca expongas este token en el código del lado del cliente (Navegador).

Seguridad Recomendada: Iframe Container

Para la mejor seguridad y aislamiento de estilos, recomendamos renderizar el HTML recibido dentro de un <iframe> usando el atributo srcdoc. Nuestro checkout es totalmente responsivo y se adaptará automáticamente al ancho del contenedor que le asignes, permitiendo una integración perfecta tanto en paneles laterales como en secciones centrales.

Endpoints

El recurso principal para generar un pago es el Payment Intent. Este endpoint es el corazón de la integración y te permite configurar cada detalle de la transacción.

POST /v1/payment-intent

Genera un checkout dinámico inyectable. Valida las credenciales y devuelve el fragmento HTML del formulario de pago.

Request Body (JSON)

Parámetro Tipo Descripción
name string Nombre oficial del producto o servicio.
description string Detalles adicionales de la compra.
subtotal_iva number Monto base sobre el cual se calcula el IVA.
subtotal_iva0 number Monto base exento de IVA (IVA 0%).
iva number Valor total del IVA calculado.
ice number Valor total del Impuesto ICE.
first_name string Nombre del pagador.
last_name string Apellido del pagador.
email string Correo electrónico para el envío del recibo.
phone_number string Número de contacto opcional.
styles object Configuración visual (primaryColor, buttonRadius).
logo_url string Enlace a la imagen del logo de tu empresa.
metadata object Campos adicionales personalizados (JSON).

Response

Status: 200 OK

Content-Type: text/html

El cuerpo de la respuesta contiene el fragmento HTML del checkout inyectable, listo para ser renderizado en el navegador del usuario final.

Ejemplos de Código

Utiliza nuestras demos oficiales para acelerar tu desarrollo en el lenguaje que prefieras:

📦

Repositorio de Demos

Encuentra los ejemplos completos y listos para ejecutar en nuestro GitHub Oficial:

GitHub: frqtal-links-demo 
curl -X POST https://api.frqtal.com/v1/payment-intent \
  -H "identity-frq-token-p: TU_API_TOKEN_AQUÍ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Producto Digital Premium",
    "description": "Suscripción Anual - Acceso Ilimitado",
    "subtotal_iva": 100.0,
    "subtotal_iva0": 0.0,
    "iva": 12.0,
    "ice": 0.0,
    "first_name": "Juan",
    "last_name": "Pérez",
    "email": "[email protected]",
    "phone_number": "+593987654321",
    "logo_url": "https://tusitio.com/logo.png",
    "styles": {
      "primaryColor": "#895ff4",
      "buttonRadius": "12px"
    },
    "metadata": {
      "order_id": "ORD-123",
      "tier": "gold"
    }
  }'
const response = await fetch("https://api.frqtal.com/v1/payment-intent", {
  method: "POST",
  headers: {
    "identity-frq-token-p": "TU_API_TOKEN_AQUÍ",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Producto Digital Premium",
    description: "Suscripción Anual - Acceso Ilimitado",
    subtotal_iva: 100.0,
    subtotal_iva0: 0.0,
    iva: 12.0,
    ice: 0.0,
    first_name: "Juan",
    last_name: "Pérez",
    email: "[email protected]",
    phone_number: "+593987654321",
    logo_url: "https://tusitio.com/logo.png",
    styles: {
      primaryColor: "#895ff4",
      buttonRadius: "12px"
    },
    metadata: {
      order_id: "ORD-123",
      tier: "gold"
    }
  }),
});

const checkoutHtml = await response.text();
// Inyecta checkoutHtml en tu sitio web
import urllib.request
import json

data = {
    "name": "Producto Digital Premium",
    "description": "Suscripción Anual - Acceso Ilimitado",
    "subtotal_iva": 100.0,
    "subtotal_iva0": 0.0,
    "iva": 12.0,
    "ice": 0.0,
    "first_name": "Juan",
    "last_name": "Pérez",
    "email": "[email protected]",
    "phone_number": "+593987654321",
    "logo_url": "https://tusitio.com/logo.png",
    "styles": {
        "primaryColor": "#895ff4",
        "buttonRadius": "12px"
    },
    "metadata": {
        "order_id": "ORD-123"
    }
}

req = urllib.request.Request(
    "https://api.frqtal.com/v1/payment-intent", 
    data=json.dumps(data).encode('utf-8'),
    method='POST'
)
req.add_header('identity-frq-token-p', 'TU_API_TOKEN_AQUÍ')
req.add_header('Content-Type', 'application/json')

with urllib.request.urlopen(req) as response:
    checkout_html = response.read().decode('utf-8')
    # Renderiza checkout_html en tu template HTML
<?php
$api_url = "https://api.frqtal.com/v1/payment-intent";
$api_token = "TU_API_TOKEN_AQUÍ";

$payment_data = [
    "name" => "Producto Digital Premium",
    "description" => "Suscripción Anual - Acceso Ilimitado",
    "subtotal_iva" => 100.0,
    "subtotal_iva0" => 0.0,
    "iva" => 12.0,
    "ice" => 0.0,
    "first_name" => "Juan",
    "last_name" => "Pérez",
    "email" => "[email protected]",
    "phone_number" => "+593987654321",
    "logo_url" => "https://tusitio.com/logo.png",
    "styles" => [
        "primaryColor" => "#895ff4",
        "buttonRadius" => "12px"
    ],
    "metadata" => [
        "order_id" => "ORD-123"
    ]
];

$ch = curl_init($api_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payment_data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "identity-frq-token-p: $api_token",
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
// El $response contiene el fragmento HTML del checkout
curl_close($ch);
?>
import React, { useState, useEffect } from 'react';

function SecureCheckout() {
  const [checkoutHtml, setCheckoutHtml] = useState('');

  useEffect(() => {
    // 1. Llama a tu Backend para obtener el HTML de Frqtal
    fetch('/api/frqtal-checkout')
      .then(res => res.text())
      .then(html => setCheckoutHtml(html));
  }, []);

  return (
    <div style={{ width: '100%', maxWidth: '450px', margin: '0 auto' }}>
      {/* 
          2. Renderizado Seguro vía Iframe (Recomendado)
          Evita el uso de dangerouslySetInnerHTML para mayor seguridad.
      */}
      <iframe
        srcDoc={checkoutHtml}
        title="Frqtal Links Checkout"
        style={{
          width: '100%',
          minHeight: '520px',
          border: 'none',
          borderRadius: '12px',
          overflow: 'hidden'
        }}
        sandbox="allow-scripts allow-forms allow-same-origin"
      />
    </div>
  );
}