> ## Documentation Index
> Fetch the complete documentation index at: https://www.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Access and data

> Which credentials Flow payments uses, why the flow ID must be shared only with the payer, what the payer can see compared with your server, and where to decide fulfillment.

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

| Credential | Held by | Allows |
| - | - | - |
| Environment API token | Your server only | Creating flows and payment links, reading the full flow, cancelling a flow in `initiated`, and checking and claiming fees you added |
| Flow ID | The payer's page | Reading the payer's view of the flow, listing the exchanges it supports, and attaching a payment source |
| Flow session token | The payer's device | Requesting quotes, approving and reporting the payment, and cancelling the flow |

The API token needs the `flow.write` permission, described in [API token permissions](https://www.dynamic.xyz/docs/platform/dashboard/api-token-permissions.md#flow-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.

| Data | Payer's view | Your server |
| - | - | - |
| States, amounts, `memo`, `failure`, payment source, and the source transaction hash | Yes | Yes |
| Destination address (`toAddress`, also inside `settlement`) | Replaced with a placeholder | Yes |
| Settlement transaction hash (`settlementTxHash`) | No | Yes |
| Settlement and destination configuration | No | Yes |
| Fee configuration and the payer's refund address | No | No |

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](https://www.dynamic.xyz/docs/flow/webhooks.md) 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](https://www.dynamic.xyz/docs/flow/lifecycle-walkthrough.md#amounts-you-will-see).

## Related

* [Screening](https://www.dynamic.xyz/docs/flow/screening.md) describes which addresses Dynamic screens and which it does not.
* [Payment sources](https://www.dynamic.xyz/docs/flow/payment-sources.md#choosing-which-sources-to-offer) explains why the list of payment methods shown in a UI is not an enforcement control.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.