Skip to main content

Payment Flow

A payment moves through four steps: your server creates it, the customer pays it, Finomesh notifies you, and your server verifies the outcome before fulfilling.

  1. Create — your server calls POST /api/v1/payments with the invoice currency, amount, and your callbackUrl (hosted mode — API mode sends webhookUrl instead). The response contains the payment paymentUid and the paymentUrl to redirect the customer to. The payable assets (amount, fees, deposit address) live on the hosted checkout, not in this response.
  2. Redirect — send the customer to the hosted checkout at https://checkout.finomesh.com/p/{paymentId}. They pick an asset and pay; Finomesh watches the chain and confirms the deposit.
  3. Get notified — the customer's browser is redirected back to your callbackUrl, and (if you set a webhookUrl) Finomesh POSTs a signed webhook to your server. Both are thin triggers — they carry only paymentId and status, never amounts.
  4. Verify — your server calls POST /api/v1/payments/{id}/verify. The response is the single source of truth: the real status plus the expected and received amounts. Fulfil the order based on this response only.
Never trust the callback

The callback is a plain browser redirect — anyone can craft callbackUrl?status=SUCCESS by hand. Always confirm the outcome server-side with verify before fulfilling an order.

Next​