API reference

Quick start

1. Sign up, connect Square, and copy a secret key from Developers in the dashboard.
2. Create a checkout session and redirect the buyer to its checkout_url.
3. Handle checkout.session.completed at your webhook endpoint and fulfill the order.

curl https://YOUR-VINGATE-DOMAIN/api/v1/checkout/sessions \
  -H "Authorization: Bearer vg_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "amount": 2500,
    "currency": "USD",
    "description": "Order #1001",
    "success_url": "https://yourstore.com/thanks",
    "cancel_url": "https://yourstore.com/cart",
    "metadata": { "order_id": "1001" }
  }'

Authentication

Send your secret key as a bearer token. vg_test_ keys use the Square sandbox (no real money). vg_live_ keys take real payments and need an active plan. Never use secret keys in a browser or app.

Authorization: Bearer vg_live_...

Roll a key from the dashboard to rotate it: the old key keeps working for 24 hours.

A key belongs to one business. If your account has several businesses, each store uses its own business's key, and its payments go to that business's Square account.

Account

curl https://YOUR-VINGATE-DOMAIN/api/v1/account -H "Authorization: Bearer vg_live_..."

Checkout sessions

{
  "id": "cs_9dQ2...",
  "object": "checkout.session",
  "livemode": false,
  "status": "open",
  "amount": 2500,
  "currency": "USD",
  "checkout_url": "https://YOUR-VINGATE-DOMAIN/c/cs_9dQ2...",
  "payment": null,
  "metadata": { "order_id": "1001" },
  "expires_at": "2026-10-12T19:30:00.000Z"
}

Payments

Refunds

curl https://YOUR-VINGATE-DOMAIN/api/v1/refunds \
  -H "Authorization: Bearer vg_test_..." -H "Content-Type: application/json" \
  -d '{ "payment_id": "pay_...", "amount": 1000, "reason": "Damaged item" }'

Front sites

A front site is a second site the processor is shown instead of the store. Pairing is two hosts and a one-time code: this endpoint pings the site, and returns an approve_url the merchant opens on that site. Nothing is written until its own admin approves, and a cloaked business cannot mint a Stripe account without a confirmed pair.

curl https://YOUR-VINGATE-DOMAIN/api/v1/pairs \\
  -H "Authorization: Bearer vg_test_..." -H "Content-Type: application/json" \\
  -d '{ "front_url": "https://shop.example", "mode": "adopt", "site": "https://peptides.example" }'

The front site redeems the code at POST /pairs/confirm (no key) with its own front_url, name and optional logo_url; only the origin the code was made for is accepted, and the answer carries a revoke token it uses at POST /pairs/:id/revoke to remove itself. GET /pairs/preview?code= is the consent payload both screens render.

Webhooks

Events:

• checkout.session.completed
• checkout.session.expired
• payment.succeeded
• payment.failed
• refund.succeeded
• refund.failed
• dispute.created
• dispute.resolved
• payout.completed

Every delivery has a VinGate-Signature: t=<unix>,v1=<hex> header: an HMAC-SHA256 of <t>.<raw body> with your secret. Reject timestamps older than 5 minutes. Delivery is at least once, so dedupe on event.id. Failed deliveries retry 7 times over about 32 hours; you can resend from the dashboard.

// Node.js (Express): use the raw body, not parsed JSON
const crypto = require("crypto");
app.post("/webhooks/vingate", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("VinGate-Signature") || "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", process.env.VINGATE_WEBHOOK_SECRET)
    .update(`${parts.t}.${req.body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const ok = fresh && parts.v1 && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  if (!ok) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  if (event.type === "checkout.session.completed") fulfill(event.data.object.metadata.order_id);
  res.sendStatus(200);
});

# Python (Flask)
import hmac, hashlib, time, json
@app.post("/webhooks/vingate")
def vingate_webhook():
    parts = dict(p.split("=", 1) for p in request.headers.get("VinGate-Signature", "").split(","))
    body = request.get_data(as_text=True)
    expected = hmac.new(SECRET.encode(), f"{parts.get('t')}.{body}".encode(), hashlib.sha256).hexdigest()
    if abs(time.time() - int(parts.get("t", 0))) > 300 or not hmac.compare_digest(expected, parts.get("v1", "")):
        return "", 400
    event = json.loads(body)
    return "", 200

Pagination

List endpoints return newest first: { "object": "list", "data": [...], "has_more": true }. Pass limit (1 to 100, default 10) and starting_after (the last id from the previous page).

curl "https://YOUR-VINGATE-DOMAIN/api/v1/payments?limit=50&starting_after=pay_..." -H "Authorization: Bearer vg_live_..."

Errors

{ "error": { "type": "invalid_request_error", "message": "amount: Too small", "param": "amount" } }

• 400 invalid_request_error: bad parameters.
• 401 authentication_error: missing, invalid, revoked or expired key.
• 402 permission_error: live key without an active plan.
• 404 not_found_error.
• 429 rate_limit_error.
• 500 api_error: retry with the same Idempotency-Key.

Rate limits

Live keys: 120 requests per minute per key. Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 includes Retry-After. Test keys are not rate limited.

Testing

Test keys use the Square sandbox. Use any future expiry date and any ZIP unless noted.

Use the dashboard's "Send test event" button to check your webhook handler without making a payment.