Skip to main content

Backend Integration

Before rendering the SmartPay button on your frontend, your backend must create a payment process (preorder) through the ApoloPay Gateway API. This returns a process ID that the frontend component needs to initialize.

Endpoint​

POST /payment-button/process/preorder

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

Swagger API Reference​

For a complete interactive API reference, you can use our live Swagger UI: 👉 Swagger UI - Gateway API

Authentication​

Include your Private Key (secret key) in the request header:

x-secret-key: YOUR_SECRET_KEY
Testing without an account?

Use the shared Sandbox / Test Keys → instead of YOUR_SECRET_KEY to create test preorders.

Request Body​

{
  "amount": 25.5,
  "metadata": {
    "orderId": "ORD-9821",
    "customerEmail": "[email protected]"
  }
}
FieldTypeRequiredDescription
amountnumber✅The payment amount to process
metadataobject❌Additional data about the order (max ~10KB). This data will be included in webhook notifications

Response​

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

The process ID is result.id — a UUID that you pass to your frontend to initialize the SmartPay button. Until the customer completes the payment, result.status stays pre_order.

Code Examples​

cURL​

curl -X POST https://pb-api.apolopay.app/payment-button/process/preorder \
  -H "Content-Type: application/json" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -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 creating payment:", error);
    res.status(500).json({ error: "Failed to create payment" });
  }
});

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="Failed to create payment")

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

Security Best Practices​

danger
  • Never expose your secret key in frontend code or public repositories
  • Store it as an environment variable on your server
  • Always make the preorder call from your backend, never from the client

Next Steps​