Callbacks

When creating pay-in or payout orders, you can specify callback_url. When an order reaches a final status (success or failed), we send a notification to this URL.

How it works

1. Order reaches final status → we send GET request to your callback_url
2. The callback is a signal only — it tells you to fetch the order details
3. Your server should call GET /order_details with id or external_id to get the full order data

Callback URL

Set callback_url when initializing pay-in or payout:

Code
{
  "amount": 500,
  "currency": "EUR",
  "external_order_id": "66a0e20c-cf87-4077-8e2e-46b487879aa9",
  "method": "P2P_CARD",
  "callback_url": "https://merchant.example.com/callback?order_id=66a0e20c-cf87-4077-8e2e-46b487879aa9"
}

You can include your external_order_id in the URL (e.g. as a query parameter) so that when the callback arrives, you know which order to fetch via /order_details?external_id=....

Retry policy

If your server returns an error (5xx, timeout, connection refused) or does not respond, we retry the callback each 5 minutes with limit in 20 requests.

Implementation example

Your callback handler should:

1. Return 200 OK as soon as possible (e.g. acknowledge receipt)
2. Process the update asynchronously — fetch /order_details and update your system
3. Be idempotent — the same callback may be delivered multiple times due to retries

Code
// Express.js example
app.get("/callback", async (req, res) => {
  // 1. Respond immediately
  res.status(200).send("OK");

  // 2. Process async — get order_id from your URL or query params
  const externalOrderId = req.query.order_id;
  const order = await fetchOrderDetails(externalOrderId);
  await updateOrderInDatabase(order);
});

async function fetchOrderDetails(externalId) {
  const signature = signRequest(apiSecret, "GET", `/order_details?external_id=${externalId}`, "");
  const res = await fetch(`https://api.frmpay.com/order_details?external_id=${encodeURIComponent(externalId)}`, {
    headers: {
      "X-API-Key": apiKey,
      "X-Signature": signature,
    },
  });
  return res.json();
}