Integrate Firstguard payments into your shop or app

Getting started

Introduction

The Firstguard API lets you accept account-to-account payments (Pay by Bank) in your shop, app or point of sale. Everything runs over HTTPS with JSON bodies. You authenticate every request with an API key, create payments with a single call and receive the outcome on a webhook – no polling required.

All amounts are in euro with two decimals (48.00). Timestamps are ISO 8601 in UTC. Identifiers you receive from us (payment IDs, transaction IDs) are stable and safe to store.

Getting started

Using the sandbox environment

The sandbox is a complete copy of production where no real money moves. Use it to build and test your integration, then switch the two URLs to go live.

1. Create a sandbox account at https://merchant.sandbox.firstguardpayments.com. When a one-time code is requested, use 123456.
2. Point your API client at https://api.sandbox.firstguardpayments.com. Every endpoint of the reference is available there.
3. Pay test payments with the built-in Firstguard Test Bank. Choose "Approve" or "Reject" on the test bank screen to simulate both outcomes.

Getting started

Getting API keys

API keys are created in the merchant panel. Sandbox keys start with fg_test_, production keys with fg_live_.

1. Log in to the merchant panel and open Settings → API.
2. Click Add API key, give it a name (for example "Webshop") and copy the key. It is shown only once.
3. Send the key in the X-Api-Key header of every request.

X-Api-Key: fg_test_9f1c2a7e4b8d4c0e9a3f6b2d1e5c7a9b

Receive payments

Payment links & buttons (no code)

You do not need a developer to get paid. Payment links and "Pay with Firstguard" buttons are generated in the merchant panel and work in e-mails, invoices, chats and on any website.

1. Open Manage business → Payment links in the merchant panel.
2. Click Add payment link, enter the amount (or leave it open for the customer to fill in) and a description.
3. Click Get link to copy the URL, or Get button to copy an HTML snippet for your website.

<a href="https://pay.firstguardpayments.com/l/inv-2026-0142"
   class="fg-pay-button">Pay €48.00 with Firstguard</a>
<script src="https://pay.firstguardpayments.com/button.js" async></script>

Receive payments

Create a payment with the API

Send the amount, your own order reference and the URLs to return to. The response contains a redirectUrl for the customer, a paymentId for later look-ups and an expiry time (payments expire after 15 minutes by default).

curl -X POST https://api.sandbox.firstguardpayments.com/v1/payments \
  -H "X-Api-Key: fg_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-1042",
    "amount": 48.00,
    "currency": "EUR",
    "languageCode": "en",
    "successUrl": "https://yourshop.com/thank-you",
    "cancelUrl": "https://yourshop.com/cart",
    "payerName": "Anna Schmidt"
  }'

const response = await fetch("https://api.sandbox.firstguardpayments.com/v1/payments", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.FIRSTGUARD_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    orderId: "order-1042",
    amount: 48.00,
    currency: "EUR",
    languageCode: "en",
    successUrl: "https://yourshop.com/thank-you",
    cancelUrl: "https://yourshop.com/cart",
  }),
});

const payment = await response.json();
// Send the customer to the checkout
res.redirect(payment.redirectUrl);

<?php
$payload = [
  'orderId'      => 'order-1042',
  'amount'       => 48.00,
  'currency'     => 'EUR',
  'languageCode' => 'en',
  'successUrl'   => 'https://yourshop.com/thank-you',
  'cancelUrl'    => 'https://yourshop.com/cart',
];

$ch = curl_init('https://api.sandbox.firstguardpayments.com/v1/payments');
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [
    'X-Api-Key: ' . getenv('FIRSTGUARD_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS     => json_encode($payload),
]);

$payment = json_decode(curl_exec($ch), true);
header('Location: ' . $payment['redirectUrl']);

import os, requests

response = requests.post(
    "https://api.sandbox.firstguardpayments.com/v1/payments",
    headers={"X-Api-Key": os.environ["FIRSTGUARD_API_KEY"]},
    json={
        "orderId": "order-1042",
        "amount": 48.00,
        "currency": "EUR",
        "languageCode": "en",
        "successUrl": "https://yourshop.com/thank-you",
        "cancelUrl": "https://yourshop.com/cart",
    },
)

payment = response.json()
# Send the customer to the checkout
return redirect(payment["redirectUrl"])

Response 201 Created

{
  "paymentId": "pay_7Hk2mQ9xL4",
  "transactionId": "b3b8f8e2-9c2e-4c1a-8e2d-3f7b8e2c9c2e",
  "status": "initialized",
  "redirectUrl": "https://pay.firstguardpayments.com/c/7Hk2mQ9xL4",
  "qrCodeUrl": "https://api.sandbox.firstguardpayments.com/v1/payments/pay_7Hk2mQ9xL4/qr-code",
  "expiresAt": "2026-09-02T14:36:07Z"
}

After the customer has paid, they are sent back to your successUrl. Do not ship on the redirect alone – wait for the payment.paid webhook, or check the status with GET /v1/payments/{paymentId}.

Receive payments

QR codes for in-store and kiosk payments

Every payment has a QR code. Request it as a PNG and show it on a customer display, a tablet at the counter or a self-service kiosk. The customer scans it with their banking app or the Firstguard app and approves.

curl https://api.sandbox.firstguardpayments.com/v1/payments/pay_7Hk2mQ9xL4/qr-code?size=512 \
  -H "X-Api-Key: fg_test_your_key" \
  --output qr.png

The QR code stays valid until the payment expires. For a counter that is always ready, create a new payment per transaction; for a fixed amount (tips, donations, a menu item) create a reusable payment link instead.

Webhooks

Receiving webhooks

Webhooks are HTTP POST requests we send to your server whenever a payment changes status. Register an endpoint in the merchant panel under Settings → API → Webhooks (or with POST /v1/webhooks), choose the events you want and save. We retry failed deliveries with increasing intervals for up to 24 hours.

{
  "event": "payment.paid",
  "paymentId": "pay_7Hk2mQ9xL4",
  "transactionId": "b3b8f8e2-9c2e-4c1a-8e2d-3f7b8e2c9c2e",
  "orderId": "order-1042",
  "amount": 48.00,
  "currency": "EUR",
  "status": "paid",
  "statusMessage": "Accepted by bank",
  "date": "2026-09-02T14:21:07Z"
}

Respond with HTTP 200 within 10 seconds. Handle events idempotently: the same event can be delivered more than once, so use paymentId and status to decide whether you have processed it already.

Webhooks

Webhook signature verification

Every webhook carries an X-Signature header: an HMAC-SHA256 of the raw request body, created with the secret key shown next to your webhook in the merchant panel. Verify it before you trust the payload.

const crypto  = require("crypto");
const express = require("express");
const app = express();

app.post("/webhooks/firstguard", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto
    .createHmac("sha256", process.env.FIRSTGUARD_WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");

  const received = req.headers["x-signature"] || "";
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
    return res.status(400).send("invalid signature");
  }

  const event = JSON.parse(req.body);
  if (event.status === "paid") {
    markOrderAsPaid(event.orderId);   // your code
  }
  res.sendStatus(200);
});

<?php
$body     = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $body, getenv('FIRSTGUARD_WEBHOOK_SECRET'));

if (!hash_equals($expected, $received)) {
    http_response_code(400);
    exit('invalid signature');
}

$event = json_decode($body, true);
if ($event['status'] === 'paid') {
    mark_order_as_paid($event['orderId']);   // your code
}
http_response_code(200);

Plugins

WooCommerce plugin

Adds "Firstguard – Pay by Bank" as a payment method to the WooCommerce checkout. Orders are marked as paid automatically through the webhook.

1. Install the plugin. Download it from the merchant panel (Settings → Plugins), upload it under Plugins → Add new → Upload in WordPress and activate it.
2. Enter your credentials. Go to WooCommerce → Settings → Payments → Firstguard, enable the method and paste your API key. Tick "Sandbox mode" while testing.
3. Set up the webhook. Copy the webhook URL shown on the settings page (https://yourshop.com/?wc-api=firstguard) into the merchant panel and paste the secret key back into the plugin.

Plugins

Magento 2 plugin

1. Install the module. Download it from the merchant panel and install it with Composer, then run bin/magento setup:upgrade and bin/magento cache:flush.
2. Enter your credentials. Under Stores → Configuration → Sales → Payment Methods → Firstguard, enable the method, choose Sandbox or Production and paste the matching API key.
3. Set up the webhook. Register https://yourshop.com/firstguard/webhook in the merchant panel and paste the secret key into the module configuration.

Plugins

Shopware 6 plugin

1. Install the plugin. Upload the ZIP under Extensions → My extensions → Upload extension, then install and activate it.
2. Enter your credentials. Open the extension configuration, paste your API key and select the sales channels that should offer Firstguard.
3. Assign the payment method. Under Settings → Payment methods, activate "Firstguard – Pay by Bank" and add it to your sales channel.
4. Set up the webhook. Register https://yourshop.com/firstguard/webhook in the merchant panel and paste the secret key into the plugin configuration.

Reference

Errors, idempotency & limits

Errors use standard HTTP status codes with a JSON body that explains what went wrong:

{
  "error": {
    "code": "validation_error",
    "message": "amount must be greater than 0",
    "field": "amount"
  }
}

Send an Idempotency-Key header (any unique string, for example your order number) with POST requests. If a request times out, repeat it with the same key and you will never create a payment twice.