Skip to main content
Flow payments splits a payment between your server, which holds an API token, and the payer’s page, which holds only a flow ID and a session token. This page explains what each credential allows, what each side can read, and which responsibilities stay with you.

​
Credentials

The API token needs the flow.write permission, described in API token permissions. Keep it on your server, read it from an environment variable or a secrets manager, and never send it to a browser or app. The session token is issued when the payer attaches a payment source. The SDK stores it on the payer’s device and sends it with each request that needs it. It stays valid until the flow’s expiry time, and it stops working earlier in these cases:
  • The payer attaches a source again, which issues a new token and invalidates the previous one.
  • The flow is cancelled, fails, or expires.
  • Settlement reaches completed or failed.

​
Treat the flow ID as a capability

The flow ID, together with your environment ID, is enough to read the payer’s view of the flow and to attach a payment source before the payment is sent. Attaching a source issues a new session token, so anyone who holds the flow ID can replace the payer’s session while the flow is still open. This is how a payer resumes on another device, and it is also why the flow ID must stay private.
  • Share the flow ID only with the payer it was created for.
  • Do not put it in public pages, analytics, logs that others can read, or URLs that are indexed.
  • Treat a payment link the same way. The link encodes the environment ID and the flow ID, so anyone who has the link can open the payment.
  • Do not put secrets or personal data in the flow’s memo. The payer’s view includes it.

​
What the payer can see and what your server can see

The payer’s page receives a reduced view of the flow. Your server, using its API token, receives the full flow. Your webhook endpoint receives data that the payer’s view does not include, such as the destination address in the quoted event, the refund address in the source_attached event, and the settlement transaction hash. Protect your webhook endpoint and the data it stores accordingly.

​
Decide fulfillment on your server

The payer’s page runs on a device you do not control, so a value it reports can be wrong or altered. Decide whether to fulfill an order, credit a balance, or ship goods on your server:
  • Act on signed webhooks after you verify their signatures, or read the flow from your server with the API token.
  • Treat a payment as done only when settlementState is completed.
  • In deposit mode, credit the delivered amount reported by the flow, not the amount the payer’s page displays. See Amounts you will see.
  • Screening describes which addresses Dynamic screens and which it does not.
  • Payment sources explains why the list of payment methods shown in a UI is not an enforcement control.
Last modified on October 27, 2026