Return to shop

When the payer is finished, Paydot offers them a return to shop step. Following it redirects their browser to the callback URL you configured under Online Payments in the portal, with two query parameters appended.

Requirements for the callback URL

Requirement	Detail
Scheme	https only.
Length	500 characters or fewer.
Query string	Not allowed. Paydot appends its own, and a second ? would produce an unusable URL.
Fragment	Not allowed.
Host	A dotted domain name, with an optional port.

A callback URL is mandatory. Online payments cannot be switched on until one is saved.

What arrives

302 Found
Location: https://shop.example/paydot/return?paymentId=payment-id-...&data=order-9987

Parameter	Value
paymentId	The Paydot payment id. Use it to fetch the payment.
data	Whatever you sent as data when you generated the link.

Both values are URL-encoded. A data value containing & or = cannot break out and forge a second parameter, so decode both before use rather than pattern-matching the raw query string.

No data means the literal string null

If you generated the link without data, the parameter is still present and its value is the four characters null:

?paymentId=payment-id-...&data=null

It is not omitted, and it is not an empty string. Handle data=null explicitly, or you will store the word null as somebody’s order id.

The callback is best-effort

The redirect happens because the payer chose to follow the return step. Nothing else triggers it.

• A payer who closes the tab, loses their connection or walks away never arrives, even though their payment may still complete perfectly well.
• The callback carries no status and no signature. A request landing on your callback URL proves only that a browser followed a link.
• The payer’s status when they return is whatever it is at that moment. They are sent back on any status, including PENDING, INCOMPLETE and UNKNOWN, because leaving is their decision and not something Paydot blocks until the bank has made up its mind.
• If online payments are switched off, or the callback URL is cleared, the return step keeps the payer on a Paydot receipt instead. Payments already in flight when you change that setting do not come back to you.

Fetch before you fulfil

Treat the callback as a signal to go and look, never as the result. On arrival, either fetch the payment with GET /payments/{paymentId} or wait for the webhook event. Both carry a status; the callback does not.

Correlating the payer with your order

data comes back on the callback and the webhook, never on the status API

data reaches you in two places: as the data query parameter here, and as data.payment.data on the webhook event.

It is not on GET /payments/{paymentId}. That response has no data field at all. If you fetch a payment by id, correlate on the paymentId you stored when you generated the link.

The generate-link response contains only url — it does not tell you the payment id, because no payment exists yet. The payment is created when the payer initiates it. So store your data value against your own order when you generate the link, and record the paymentId the first time you see it, on this callback or on the webhook event.

A worked arrival

app.get("/paydot/return", async (req, res) => {
  const { paymentId, data } = req.query;
  const orderId = data === "null" ? null : data;

  const payment = await fetch(`https://pay-api.paydot.eu/payments/${paymentId}`)
    .then((response) => response.json());

  if (payment.status === "EXECUTED" || payment.status === "SETTLED") {
    return res.redirect(`/orders/${orderId}/thanks`);
  }
  return res.redirect(`/orders/${orderId}/pending`);
});

Showing the payer a page is the job here. Releasing the order is the webhook’s job, and doing it in both places is safe only if that step is idempotent.