Trust

FAQ

Short answers, each linking to the page with the long one.

What is the difference between a deposit request and a deposit?#

The request is the document you issue. The deposit is the funds that answer it at a one-time address. The API resource is the request, and you read the deposit's state from it. See Deposit requests and deposits.

Can I add line items or tax?#

No. State the amount directly and attach a PDF for an itemised breakdown or any jurisdiction-specific content. Payday stores and hashes the file but never parses it, and does not model line items, tax, or fiat.

Which asset and network can pay?#

One exact Circle-issued USDC contract on one chain per environment: Monad mainnet in production, Monad testnet in the sandbox. Read chain and token from the request. Bridged USDC, look-alike tokens, another network's USDC, and gas tokens do not count and may be unrecoverable. See Environments.

Why is the address null after I create a request?#

Because it does not exist yet. The address is derived from the payer's wallet signature, so it appears once the payer signs on the hosted page. Wait for deposit_request.ready or poll until address is set. See One request, one address.

What should I give the payer?#

The deposit_url. It shows everything they need, withholds what they should not see, and handles the wallet step. If you build your own page, reproduce the safety guidance in Hosted checkout.

A payer says they paid. Why has nothing changed?#

Payday credits only finalized transfers. A wallet can show a transaction as confirmed before the chain finalizes it and before Payday's indexer reaches it. Check as_of, indexer_freshness, and the request's transfers; if the transfer went to the right address from the right token, it will be credited. If it was the wrong token or the wrong network, it may be unrecoverable.

What happens with partial, excess, or late funds?#

Partial transfers accumulate. Excess goes back to the payer's wallet at settlement. Funds still short at the deadline, or arriving after it, go back to the payer's wallet. Nothing is held by Payday. See Where the USDC goes.

Can I cancel or refund through Payday?#

Cancelling is advisory: it stops Payday's pages from presenting the request but cannot disable an address. There is no refund endpoint. Funds that settled to your wallet are yours to refund through your own process; funds Payday routes back to the payer go automatically, and deposit_request.recovered_funds tells you when.

The payer sent from a different wallet than the one they signed with.#

The funds count and settle, but the request is flagged likely unsolicited and no Proof of Payment is issued, because the attested wallet did not pay. Anything returned goes to the attested wallet, not the sending one. Treat the flag as a prompt to check who actually paid.

Should I poll or use webhooks?#

Webhooks for automation, long polling for a screen that is open now. Verify the signature over the raw body, reject stale timestamps, and deduplicate on the event id. See Webhooks.

What does needs_attention mean?#

Automatic movement stopped because Payday could not safely continue. Do not send more funds. Follow attention.action and contact support with the request id and the API request id. Funds are neither lost nor delivered until an operator releases it.

What is Proof of Payment and who can verify it?#

A JSON record of the document, the payer's wallet signature, the address derivation, the transfers, and the settlement transaction. Anyone can recompute it offline, and the checks are published. See Proof of Payment.

How should I store and rotate API keys?#

In a secret manager, never in a browser, a repository, a URL, or a log. Roll a key from the dashboard and the old one keeps working for 24 hours; revoke for a compromise. A key cannot mint another key. See Authentication.

How are amounts and deadlines encoded?#

Amounts are decimal strings with six decimals beside integer base-unit strings; never use floating point. Deadlines are RFC 3339 in UTC; set them with expires_in seconds or expires_at, default 24 hours, between 10 minutes and 366 days.

Is there a sandbox?#

Yes: https://api.sandbox.payday.sh with payday_test_ keys, on Monad testnet with Circle's test USDC and the same real indexing and finality. See Environments.

Where can I get help?#

Email support@payday.sh with the request id and the dr_ id. Never send an API key, a verification code, a webhook secret, or more data than the question needs.