Saltar al contenido principal

Integración Backend

Antes de renderizar el botón SmartPay en tu frontend, tu backend debe crear un proceso de pago (preorden) a través de la API Gateway de ApoloPay. Esto devuelve un process ID que el componente frontend necesita para inicializarse.

Endpoint​

POST /payment-button/process/preorder

URL Base: https://pb-api.apolopay.app

Referencia API (Swagger)​

Para una referencia completa e interactiva de la API, puedes usar nuestro Swagger UI en vivo: 👉 Swagger UI - API Gateway

Autenticación​

Incluye tu Llave Privada (secret key) en el header de la petición:

x-secret-key: TU_LLAVE_SECRETA
¿Probando sin una cuenta?

Usa las Llaves de Prueba (Sandbox) → en lugar de TU_LLAVE_SECRETA para crear preórdenes de prueba.

Cuerpo de la Petición (Request Body)​

{
  "amount": 25.5,
  "metadata": {
    "orderId": "ORD-9821",
    "customerEmail": "[email protected]"
  }
}
CampoTipoRequeridoDescripción
amountnumber✅El monto del pago a procesar
metadataobject❌Datos adicionales sobre el pedido (máximo ~10KB). Estos datos se incluirán en las notificaciones webhook

Respuesta (Response)​

{
  "success": true,
  "message": "OK",
  "result": {
    "id": "660cbb7f-6d78-4638-862b-1dbc3911ecbe",
    "amount": 25.5,
    "status": "pre_order",
    "createdAtMs": 1790095153955
  }
}

El process ID es result.id — un UUID que pasarás a tu frontend para inicializar el botón SmartPay. Hasta que el cliente complete el pago, result.status se mantiene en pre_order.

Ejemplos de Código​

cURL​

curl -X POST https://pb-api.apolopay.app/payment-button/process/preorder \
  -H "Content-Type: application/json" \
  -H "x-secret-key: TU_LLAVE_SECRETA" \
  -d '{
    "amount": 25.50,
    "metadata": {
      "orderId": "ORD-9821",
      "customerEmail": "[email protected]"
    }
  }'

Node.js (Express)​

const express = require("express");
const app = express();
app.use(express.json());

const APOLOPAY_SECRET_KEY = process.env.APOLOPAY_SECRET_KEY;
const APOLOPAY_API_URL = "https://pb-api.apolopay.app";

app.post("/api/create-payment", async (req, res) => {
  try {
    const { amount, orderId, customerEmail } = req.body;

    const response = await fetch(`${APOLOPAY_API_URL}/payment-button/process/preorder`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-secret-key": APOLOPAY_SECRET_KEY,
      },
      body: JSON.stringify({
        amount,
        metadata: { orderId, customerEmail },
      }),
    });

    const data = await response.json();
    res.json({ processId: data.result.id });
  } catch (error) {
    console.error("Error al crear pago:", error);
    res.status(500).json({ error: "Fallo al crear pago" });
  }
});

Python (FastAPI)​

import httpx
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import os

app = FastAPI()

APOLOPAY_SECRET_KEY = os.getenv("APOLOPAY_SECRET_KEY")
APOLOPAY_API_URL = "https://pb-api.apolopay.app"

class PaymentRequest(BaseModel):
    amount: float
    order_id: str | None = None
    customer_email: str | None = None

@app.post("/api/create-payment")
async def create_payment(request: PaymentRequest):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{APOLOPAY_API_URL}/payment-button/process/preorder",
            headers={
                "Content-Type": "application/json",
                "x-secret-key": APOLOPAY_SECRET_KEY,
            },
            json={
                "amount": request.amount,
                "metadata": {
                    "orderId": request.order_id,
                    "customerEmail": request.customer_email,
                },
            },
        )

        if response.status_code != 200:
            raise HTTPException(status_code=500, detail="Fallo al crear pago")

        data = response.json()
        return {"processId": data["result"]["id"]}

Mejores Prácticas de Seguridad​

peligro
  • Nunca expongas tu llave secreta en el código del frontend o repositorios públicos
  • Guárdala como una variable de entorno en tu servidor
  • Siempre realiza la llamada de preorden desde tu backend, nunca desde el cliente

Siguientes Pasos​