Implementación

La implementación de ePayco Smart Checkout se realiza mediante una integración JavaScript simple y directa que te permite desplegar el checkout con cualquier evento en tu aplicación web.

Uso

Creación de la sesión desde el backend

El primer paso para implementar ePayco Smart Checkout es crear una sesión de checkout cuando el cliente esté listo para realizar la compra. Esta sesión debe ser creada desde tu backend favorito mediante una petición a nuestras APIs, la cual generará un ID de sesión único que posteriormente utilizarás para inicializar el componente de ePayco Smart Checkout en el frontend y garantizar que la sesión esté correctamente vinculada con tu sistema de gestión de órdenes.

Autenticación con Apify

Antes de crear la sesión de ePayco Smart Checkout, debes autenticarte con los servicios de Apify de ePayco para obtener un token de acceso. Este proceso requiere que seas un usuario registrado en ePayco y utiliza autenticación Basic enviando tu PUBLIC_KEY y PRIVATE_KEY (las cuales puedes obtener en tu dashboard de ePayco en la sección de Configuración → Personalizaciones → Llaves secretas. en los headers de la petición. El token que obtendrás de este endpoint te permitirá firmar las solicitudes posteriores necesarias para crear la sesión de ePayco Smart Checkout de forma segura.

Solicitud

curl --location --request POST 'https://apify.epayco.co/login' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <PUBLIC_KEY:PRIVATE_KEY en base64>'

Respuesta exitosa

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhcGlmeWVQYXljb0pXVCIsInN1YiI6MTU1NTk3MywiaWF0IjoxNzYwNDkyNzMyLCJleHAiOjE3NjA0OTM5MzIsInJhbmQiOiI5YzU1NjhlYTEyZjI3MWM0OWUzMTIzYWRhMmE3M2VmODcwMTciLCJyZXMiOmZhbHNlLCJpbmEiOmZhbHNlLCJndWkiOjExNTI2NDYsInV1aWQiOiIzZjYwOGY0ZS00YWM4LTQ4NDYtYmRjZS0xMmViZjJmZTkyZDMiLCJzY29wZSI6Im1hc3RlciJ9.SSI-6nPQDwN2bS0yK-K2-U-1gOgC7pZB0BFN3_amqh8"
}

Autenticación con Apify

Una vez obtenido el token de autenticación, el siguiente paso es crear la sesión de Smart Checkout que generará el sessionId necesario para inicializar el componente en el frontend. Esta petición debe incluir la información de la transacción como el nombre del producto, descripción, monto, moneda, etc. El sessionId retornado será utilizado para abrir el Smart Checkout de pago en tu sitio web.

Solicitud

curl --location 'https://apify.epayco.co/payment/session/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{APIFY_TOKEN}}' \
--data '{
    "checkout_version": "2",
    "name": "Shops Online S.A.S",
    "currency": "COP",
    "amount": 200000
}'

Todas las propiedades disponibles que describen más abajo.

Respuesta exitosa

{
    "success": true,
    "titleResponse": "Session created successfully",
    "textResponse": "Session created successfully",
    "lastAction": "create session",
    "data": {
        "sessionId": "68eefce71d65f1d39c0f6dad",
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4ZWVmY2U3MWQ2NWYxZDM5YzBmNmRhZCIsImNyZWF0ZWRfYXQiOiIyMDI1LTEwLTE1VDAxOjQ2OjE1LjU1NFoiLCJpYXQiOjE3NjA0OTI3NzUsImV4cCI6MTc2MDU3OTE3NX0.BYGWqDyUxe1JDfYc2F_EhwHET0Uv-umvAJdQtf6wd9k"
    }
}

Propiedades

A continuación se describen todas las propiedades que puedes utilizar al crear una sesión de ePayco Smart Checkout. Las propiedades están organizadas en requeridas y opcionales, incluyendo objetos anidados para configuraciones avanzadas como división de pagos, campos personalizados y datos de facturación.

Ejemplo Completo

A continuación se muestra un objeto JSON completo con todas las propiedades disponibles para crear una sesión de ePayco Smart Checkout:

{
  // ==================== REQUERIDOS ====================
  "checkout_version": "2",
  "name": "Shops Online S.A. S",
  "currency": "COP",
  "amount": 20000.00, // Total a pagar

  // ==================== OPCIONALES ====================
  "description": "Buzo con capucha color negro unisex",
  "lang": "ES", // ES | EN
  "invoice": "2341233", // numero de factura
  "country": "CO", // Código alpha-2
  "taxBase": 16806.72,
  "tax": 3193.28,
  "taxIco": 0,
  "response": "https://mysite.com",
  "confirmation": "https://webhook.site/8b4bb363-099e-42e8-afe7-0bf11c59eeb1",

  // ==================== CONFIGURACIÓN (OPCIONAL) ====================
  "methodsDisable": [],
  "method": "POST", // GET | POST
  "dues": 1,

  // ==================== SPLIT PAYMENT (OPCIONAL) ====================
  "splitPayment": {
    "type": "percentage",
    "receivers": [
      {
        "merchantId": 9898,
        "amount": 15000.00,
        "taxBase": 12605.04,
        "tax": 2394.96,
        "fee": 1
      },
      {
        "merchantId": 1485968,
        "amount": 5000,
        "taxBase": 4201.68,
        "tax": 798.32,
        "fee":  1
      }
    ]
  },

  // ==================== PSE MULTICREDITO (OPCIONAL) ====================
  "PSEMultiCredit": {
    "serviceCode": "SERV-01",
    "credits": [
      {
        "code": "77700102",
        "amount": 12000.00,
        "companyIdentification": "8001234567"
      },
      {
        "code": "77700103",
        "amount": 8000.00,
        "companyIdentification": "8009876543"
      }
    ]
  },

  // ==================== EXTRAS (OPCIONAL) ====================
  "extras": {
    "extra1": "extra1",
    "extra2": "extra2",
    "extra3": "extra3",
    "extra4": "extra4",
    "extra5": "extra5",
    "extra6": "extra6",
    "extra7":  "extra7",
    "extra8": "extra8",
    "extra9": "extra9",
    "extra10": "extra10",
    "extra11": "extra11"
  },

  // ==================== BILLING (OPCIONAL) ====================
  "billing": {
    "email": "cliente@gmail.com",
    "name":  "CLiente Martinez",
    "address": "AV 18 # 18 - 17",
    "typeDoc": "CC",
    "numberDoc": "103242123",
    "callingCode": "+57",
    "mobilePhone": "312456654"
  }
}

Nota: Este ejemplo incluye todas las propiedades disponibles. Solo las propiedades requeridas checkout_version, name, currency, amount) son obligatorias. El resto son opcionales y puedes incluirlas según las necesidades de tu implementación.

Implementación en el frontend

Una vez que hayas obtenido el sessionId desde tu backend, el último paso es inicializar y mostrar el componente de ePayco Smart Checkout en tu sitio web. Primero debes incluir la librería JavaScript de ePayco en tu página, luego configurar el Smart Checkout con el sessionId obtenido y finalmente abrirlo con el evento de tu preferencia.

1. Incluir la librería de ePayco

Agrega el siguiente script en tu página HTML:

<script src="https://checkout.epayco.co/checkout-v2.js"></script>

2. Configurar y abrir el checkout

const checkout = ePayco.checkout.configure({
      sessionId: sessionId,
      type: "onpage", // "onpage" | "standard"
      test: true // Test: true | false
});

// Abrir el checkout
checkout.open();

3. Registrar hooks con setHooks()

ePayco Smart Checkout proporciona un sistema de hooks que permite responder a diferentes etapas del flujo de pago. Todos los hooks se registran en una sola llamada mediante setHooks({ onCreated, onResponse, onClosed, onErrors }) sobre el checkout retornado por configure(). Estos hooks están disponibles para los tipos de implementación onpage.

checkout.setHooks({
    onCreated: (data) => {
        console.log("Checkout creado:", data);
        // Guardar marcación de apertura, analytics, etc.
    },
    onResponse: (response) => {
        console.log("Respuesta del pago:", response);
        // Procesar la respuesta de la transacción.
    },
    onErrors: (error) => {
        console.error("Error al procesar el pago:", error);
        // Mostrar mensaje de error personalizado al usuario.
    },
    onClosed: (errors) => {
        console.log("Checkout cerrado.", errors);
        // Limpiar estado, verificar estado de transacción, redirigir custom.
    }
});

Descripción de cada hook:

- onCreated(data) Se dispara cuando se abre exitosamente el Smart Checkout. Recibe como argumento la información de la transacción creada.

- onResponse(response) Se dispara cuando el pago ha sido procesado y se obtiene la respuesta del Smart Checkout. Recibe como argumento el objeto con el resultado de la transacción (estado, referencia, monto, etc.). Ideal para confirmar el pago en el frontend o actualizar la UI.

- onErrors(error) Se activa cuando ocurre un error durante el proceso de obtener la transacción en el Smart Checkout. Recibe como argumento el detalle del error. Permite manejar errores de forma personalizada y mostrar mensajes apropiados al usuario.

- onClosed(errors) Se dispara cuando el usuario cierra el Smart Checkout, ya sea después de completar el pago o cancelar el proceso. Recibe como argumento eventuales errores ocurridos al cerrar. Ideal para limpiar el estado de la aplicación o redirigir al usuario.

Ejemplo de implementación completa con eventos:

Selecciona la pestaña del lenguaje o framework que estés utilizando. Vanilla JS es la implementación por defecto. Todos los ejemplos asumen que: (1) ya incluiste el <script> de ePayco en tu index.html (paso 1 más arriba) y (2) ya tienes un sessionId obtenido previamente desde tu backend (ver sección Creación de la sesión desde el backend). Cada ejemplo se enfoca únicamente en cómo integrar el Smart Checkout en el frontend usando configure() + setHooks({...}) + open().

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <title>Smart Checkout ePayco</title>
    <script src="https://checkout.epayco.co/checkout-v2.js"></script>
</head>
<body>
    <button id="payBtn">Pagar</button>
    <p id="status" role="status" aria-live="polite"></p>

    <script>
        // sessionId obtenido previamente desde tu backend
        // (ver sección "Creación de la sesión desde el backend").
        const sessionId = "TU_SESSION_ID";

        const payBtn = document.getElementById("payBtn");
        const statusEl = document.getElementById("status");

        payBtn.addEventListener("click", () => {
            payBtn.disabled = true;

            // 1. Configurar el checkout
            const checkout = ePayco.checkout.configure({
                sessionId,
                type: "onpage", // "onpage" | "standard"
                test: true
            });

            // 2. Registrar hooks (reciben argumentos con la info del evento)
            checkout.setHooks({
                onCreated: (data) => {
                    console.log("Checkout creado:", data);
                    statusEl.textContent = "Checkout creado.";
                },
                onResponse: (response) => {
                    console.log("Respuesta del pago:", response);
                    statusEl.textContent = "Pago procesado correctamente.";
                },
                onErrors: (error) => {
                    console.error("Error en el pago:", error);
                    statusEl.textContent = "Error al procesar el pago.";
                },
                onClosed: (errors) => {
                    console.log("Checkout cerrado.", errors);
                    statusEl.textContent = "Checkout cerrado.";
                    payBtn.disabled = false;
                }
            });

            // 3. Abrir el checkout
            checkout.open();
        });
    </script>
</body>
</html>

// PayButton.tsx — React 18+ con TypeScript
// Asegúrate de incluir el script en tu index.html:
// <script src="https://checkout.epayco.co/checkout-v2.js"></script>
import { useEffect, useState } from "react";

declare const ePayco: any;

interface PayButtonProps {
    // sessionId obtenido desde tu backend (ver sección "Creación de la sesión")
    sessionId: string;
}

export default function PayButton({ sessionId }: PayButtonProps) {
    const [scriptReady, setScriptReady] = useState(false);
    const [isLoading, setIsLoading] = useState(false);
    const [message, setMessage] = useState("");

    // SSR guard + verificación de disponibilidad del script
    useEffect(() => {
        if (typeof window === "undefined") return;
        if (typeof ePayco === "undefined") {
            setMessage("Script de ePayco no cargó correctamente.");
            return;
        }
        setScriptReady(true);
    }, []);

    const handlePayment = () => {
        if (!scriptReady) return;
        setIsLoading(true);

        // 1. Configurar el checkout
        const checkout = ePayco.checkout.configure({
            sessionId,
            type: "onpage",
            test: true
        });

        // 2. Registrar hooks (reciben argumentos con la info del evento)
        checkout.setHooks({
            onCreated: (data: any) => {
                console.log("Checkout creado:", data);
                setMessage("Checkout creado.");
            },
            onResponse: (response: any) => {
                console.log("Respuesta:", response);
                setMessage("Pago procesado.");
            },
            onErrors: (error: any) => {
                console.error("Error:", error);
                setMessage("Error en el pago.");
            },
            onClosed: (errors?: any) => {
                console.log("Cerrado.", errors);
                setMessage("Checkout cerrado.");
                setIsLoading(false);
            }
        });

        // 3. Abrir el checkout
        checkout.open();
    };

    return (
        <div>
            <button onClick={handlePayment} disabled={!scriptReady || isLoading}>
                {isLoading ? "Procesando..." : "Pagar"}
            </button>
            <p role="status" aria-live="polite">{message}</p>
        </div>
    );
}

// pay-button.component.ts — Angular 16+ standalone
// Incluye el script en tu index.html:
// <script src="https://checkout.epayco.co/checkout-v2.js"></script>
import { Component, Input, OnInit, PLATFORM_ID, inject } from "@angular/core";
import { CommonModule, isPlatformBrowser } from "@angular/common";

declare const ePayco: any;

@Component({
    selector: "app-pay-button",
    standalone: true,
    imports: [CommonModule],
    template: `
        <button (click)="handlePayment()" [disabled]="!scriptReady || isLoading">
            {{ isLoading ? "Procesando..." : "Pagar" }}
        </button>
        <p role="status" aria-live="polite">{{ message }}</p>
    `
})
export class PayButtonComponent implements OnInit {
    private readonly platformId = inject(PLATFORM_ID);

    // sessionId obtenido desde tu backend (ver sección "Creación de la sesión")
    @Input({ required: true }) sessionId!: string;

    scriptReady = false;
    isLoading = false;
    message = "";

    ngOnInit(): void {
        // SSR guard
        if (!isPlatformBrowser(this.platformId)) return;
        if (typeof ePayco === "undefined") {
            this.message = "Script de ePayco no cargó correctamente.";
            return;
        }
        this.scriptReady = true;
    }

    handlePayment(): void {
        if (!this.scriptReady) return;
        this.isLoading = true;

        // 1. Configurar el checkout
        const checkout = ePayco.checkout.configure({
            sessionId: this.sessionId,
            type: "onpage",
            test: true
        });

        // 2. Registrar hooks (reciben argumentos con la info del evento)
        checkout.setHooks({
            onCreated: (data: any) => {
                console.log("Checkout creado:", data);
                this.message = "Checkout creado.";
            },
            onResponse: (response: any) => {
                console.log("Respuesta:", response);
                this.message = "Pago procesado.";
            },
            onErrors: (error: any) => {
                console.error("Error:", error);
                this.message = "Error en el pago.";
            },
            onClosed: (errors?: any) => {
                console.log("Cerrado.", errors);
                this.message = "Checkout cerrado.";
                this.isLoading = false;
            }
        });

        // 3. Abrir el checkout
        checkout.open();
    }
}

<!-- PayButton.vue — Vue 3 Composition API -->
<!-- Incluye el script en tu index.html:
     <script src="https://checkout.epayco.co/checkout-v2.js"></script> -->
<script setup lang="ts">
import { onMounted, ref } from "vue";

declare const ePayco: any;

// sessionId obtenido desde tu backend (ver sección "Creación de la sesión")
const props = defineProps<{ sessionId: string }>();

const scriptReady = ref(false);
const isLoading = ref(false);
const message = ref("");

onMounted(() => {
    // SSR guard
    if (typeof window === "undefined") return;
    if (typeof ePayco === "undefined") {
        message.value = "Script de ePayco no cargó correctamente.";
        return;
    }
    scriptReady.value = true;
});

function handlePayment() {
    if (!scriptReady.value) return;
    isLoading.value = true;

    // 1. Configurar el checkout
    const checkout = ePayco.checkout.configure({
        sessionId: props.sessionId,
        type: "onpage",
        test: true
    });

    // 2. Registrar hooks (reciben argumentos con la info del evento)
    checkout.setHooks({
        onCreated: (data: any) => {
            console.log("Checkout creado:", data);
            message.value = "Checkout creado.";
        },
        onResponse: (response: any) => {
            console.log("Respuesta:", response);
            message.value = "Pago procesado.";
        },
        onErrors: (error: any) => {
            console.error("Error:", error);
            message.value = "Error en el pago.";
        },
        onClosed: (errors?: any) => {
            console.log("Cerrado.", errors);
            message.value = "Checkout cerrado.";
            isLoading.value = false;
        }
    });

    // 3. Abrir el checkout
    checkout.open();
}
</script>

<template>
    <div>
        <button :disabled="!scriptReady || isLoading" @click="handlePayment">
            {{ isLoading ? "Procesando..." : "Pagar" }}
        </button>
        <p role="status" aria-live="polite">{{ message }}</p>
    </div>
</template>

Nota: Todos los ejemplos usan test: true para entorno de pruebas; en producción debe cambiarse a test: false. El sessionId debe obtenerse previamente desde tu backend siguiendo la sección Creación de la sesión desde el backend arriba.