Verify Payment

Confirm a payment on your server before fulfilling an order — never trust redirects.

Placeholder API contract

Path, headers, and fields below are illustrative until the final HellOOpass API contract is published.

A redirect to your callback_url, a query parameter, or a client callback is never proof that money moved. Verification is the server-side check that closes the loop before you fulfill.

GET/v1/payments/{payment_id}

Retrieves the payment so its status can be verified — the same resource as Retrieve Payment Details.

Authentication: Secret API key (Bearer)

Verify on your server

Retrieve the payment by id with your secret API key, on your backend.
Confirm status is succeeded.
Confirm amount, currency, and reference match the order you expect.
Fulfill the order exactly once — idempotently.

const res = await fetch(
  `https://sandbox-api.helloopass.example/v1/payments/${paymentId}`,
  { headers: { Authorization: `Bearer ${process.env.HELLOOPASS_SECRET_KEY}` } },
);
const payment = await res.json();
 
if (payment.status !== "succeeded") return reject(payment.status);
if (payment.amount !== order.amountMinor) return reject("amount_mismatch");
 
await fulfillOrder(order.id); // must be idempotent

A 404 means the identifier is wrong or belongs to the other environment — see Authentication.

Never trust

Redirects — the customer can close the tab before the redirect ever fires.
Query parameters — return URL params are client-controlled and can be edited or replayed.
Client callbacks — browser and app callbacks run on devices you do not control.

Only succeeded is paid

Fulfilling while a payment is pending or processing risks releasing goods for a payment that later ends as failed.

Webhooks

Signed webhooks cover the case where the customer never returns — abandoned tabs, network failures, mobile deep-link issues. Both paths must converge on the same idempotent fulfillment logic.

Verify the signature on every webhook before trusting the payload.
Process each event exactly once so redeliveries never double-fulfill.