Getting started

Deposit requests and deposits

Payday has two primitives. A deposit request is the ask; a deposit is the funds that answer it. Everything else on this page follows from keeping the two apart.

Deposit request

the document

What you issue: an issuer and a payer, one amount, an optional heading, reference, notes, and metadata, a payer policy, a deadline, and at most one PDF. It is the API resource, it has a dr_ id, and it is immutable once issued.

Deposit

the funds

What answers it on-chain: the one-time address, the USDC transfers that reach it, and the settlement that moves the amount to your wallet. You read its state from the request: status, received, transfers.

Payday models no line items, quantities, discounts, tax, or fiat. The amount is authoritative. A PDF you attach is stored, shown to the payer, and hashed into the address, but never parsed or reconciled against the amount. To change anything about an issued request, cancel it and issue another; that is what keeps a Proof of Payment meaningful.

issuer
The party asking. Usually saved once as an issuer identity with a proven contact mailbox, so the payer can write back.
payer
The party expected to pay. Optionally linked to a saved customer; the request still stores its own snapshot.
amount
A USDC decimal with up to six fractional digits. Exactly this settles to your payout address, no more and no less.
payout_address
Your wallet. By default the wallet Payday created for your account at sign-in; any EVM address you save works too.
payer_policy
Who may pay and what they prove first. See Verifying the payer.
expires_at
The deadline, decided by chain time. Default 24 hours; 10 minutes to 366 days.

One request, one address, one payer wallet#

Every deposit request gets its own EVM address, and that address belongs to one payer wallet. It does not exist when the request is issued. It exists once the payer, on the hosted checkout, signs a short message from the wallet they intend to pay from. Payday derives the address from the issued document and that signature together, which is why address is null until then.

Issued documentparties, amount, deadline…canonicalizeAttribution hashRFC 8785 + keccakPayer's walletthe one that will payEIP-712 signsAttestation digesthash + nonce, signedSaltkeccak(hash ‖ digest)CREATE3One-time addressexists before a contractTerms the address commits totoken · amount · payout · deadline · recovery walletAnyone holding the proof can recompute every step offline.Nothing in the chain of derivation can be changed after the payer signs.
Where the one-time address comes from. The salt depends on both the document and the payer's signature, and the address commits to the settlement terms, so none of them can change afterwards.

The address is counterfactual: it is calculated before any contract is deployed at it, so USDC can arrive the moment it is shown. When Payday later deploys and executes the contract, the funds can only move under the terms the address already commits to: this token, this amount, your payout address, this deadline, and the payer's wallet as the recovery destination. Anyone may execute it; nobody can redirect it.

Two things follow, and both are worth internalising:

  • Only transfers from the attested wallet are the payer's. USDC from any other wallet still counts toward the amount and settles, but the request is flagged likely_unsolicited and no Proof of Payment will claim the payer paid it.
  • Everything Payday returns goes to the payer's own wallet, on-chain. An overpayment remainder, an expired balance, a late transfer. Nothing is held by Payday, and no one has to ask for a refund address.

Lifecycle#

A request has one public status. Clients should branch only on the values below and tolerate new fields.

awaiting_depositsome USDCpartially_depositedamount metdepositedpaid outsettledone transfer covers itdeadline passes, still shortexpiredbalance sent backreturnedneeds_attentionany status; paused
Every transition a deposit request can make. Cancellation is not a status: it is recorded on the request and asks clients to stop presenting it, but cannot disable the address.
StatusMeaning
awaiting_depositNo finalized, on-time USDC has been credited yet.
partially_depositedSome finalized USDC is credited, but less than the amount.
depositedFinalized credits reached the amount. Settlement is queued. Not yet payout finality; fulfil according to your own risk policy.
settledExactly the amount reached your payout address. Any remainder went back to the payer. The strongest state; the Proof of Payment is available.
expiredThe deadline passed before settlement. The return to the payer is pending.
returnedThe whole balance went back to the payer's wallet after expiry.
needs_attentionAutomatic movement paused. Follow attention.action on the request, or contact support. Funds are neither lost nor delivered until an operator releases it.

Separate from the status, a request also reports verification: whether the payer policy has been satisfied, and by whom. A gated request can be funded before its payer has verified, which is why the two are different facts and filter separately.

Where the USDC goes#

Finalized transfers accumulate while a request is open. Chain time, not the payer's clock or the moment they pressed send, decides whether a transfer and the eventual execution are on time. Execution at exactly the deadline is on time; a later block is not.

Exact amount, on time

amount
amount → your wallet

Several partial transfers reach the amount

amount
amount → your wallet

Still short when the deadline passes

amount
balance → payer's wallet

More than the amount, on time

amount
amount → your walletremainder → payer's wallet

Enough arrived, but execution is after the deadline

amount
balance → payer's wallet

USDC arrives after settlement

amount
forwarded → payer's wallet
Every situation and its routing. Green is your payout address; yellow is the payer's attested wallet. Payday itself never appears, because it never holds the funds.

Each return is recorded against its request in the recovered_funds ledger and raises a deposit_request.recovered_funds webhook naming the amount, the reason (overpayment, expired, or late_transfer), and the transaction. Use it to explain to a payer where a difference went.

Finality and freshness#

Payday credits only finalized transfers of the configured Circle-issued USDC contract. A wallet may show a transaction as submitted, included, or confirmed before received changes. There is intentionally no endpoint to mark a request deposited by hand.

Every read of a request tells you how current it is:

  • as_of: the block and time through which the request's state is committed;
  • indexer_freshness: the last indexed and finalized block positions;
  • transfers: every finalized transfer to the address with sender, transaction, amount, block, and whether it was credited, late, or zero-value.

The authenticated status route reports the same for the service as a whole.

Amounts#

USDC has six decimals. Every amount is returned twice: as a decimal string ("25.000000") for display, and as an integer string of base units ("25000000") for arithmetic. Do arithmetic on base units with integer or decimal types; never with binary floating point.

Proof of Payment#

A settled request can be exported as a Proof of Payment: the canonical document, the payer's wallet attestation, the salt, the addresses, the credited transfers, the settlement transaction, and a Payday-signed statement of the verification facts. From it anyone can recompute the address and check the transfers with no access to Payday. See Proof of Payment.

Safety boundaries#

  • Only the exact token.address on the returned chain.id is monitored. Bridged USDC, look-alike tokens, another network's USDC, and native gas do not count and may be unrecoverable.
  • A deposit link grants read access to the payer page and nothing else. It never exposes your payout address, metadata, customer, or policy assertions.
  • needs_attention pauses settlement and recovery, including for later transfers, until an operator resolves it.