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 processId 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

Request Body​

{
  "amount": 25.50,
  "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​

{
  "processId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

The processId is a UUID that you will pass to your frontend to initialize the SmartPay button.

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.processId });
  } 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["processId"]}

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​