Getting started

Quickstart

Issue a USDC deposit request, share its link, and watch finalized funds settle to your wallet. Five steps, one API key, no smart-contract code.

  1. Sign in and mint an API key

    Open payday.sh, choose Start Building, and enter the code emailed to you. The account is created the first time a code is accepted, with its own wallet where deposits settle by default.

    In the dashboard's API key section, generate a key. It is shown exactly once. Store it as PAYDAY_API_KEY in your server's secret store, never in a browser or a repository. A key has full authority over the account; see Authentication for rotation and revocation.

    To try against test USDC first, use the sandbox at https://api.sandbox.payday.sh with a payday_test_ key. See Environments.

  2. Issue a deposit request

    One call. The amount is used exactly as given; there are no line items. The Idempotency-Key header is required, and a retry with the same key and body returns the original request instead of creating a second one.

    Shell
    export API=https://api.payday.sh
export PAYDAY_API_KEY=payday_live_...

curl -fsS "$API/v1/deposit-requests" \
  -H "Authorization: Bearer $PAYDAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "amount": "25.00",
    "payout_address": "0x1111111111111111111111111111111111111111",
    "issuer": { "name": "Acme LLC" },
    "payer": { "name": "Customer Inc" },
    "heading": "March retainer",
    "reference": "INV-1042",
    "payer_policy": { "mode": "permissionless" },
    "expires_in": 3600
  }' | jq

    The response is the full deposit request. The fields that matter first:

    201 Created
    {
  "id": "dr_0198f80c-8d2f-7dc1-a369-90556a64f700",
  "deposit_url": "https://payday.sh/pay/dr_0198f80c-8d2f-7dc1-a369-90556a64f700",
  "status": "awaiting_deposit",
  "amount": "25.000000",
  "amount_base_units": "25000000",
  "received": "0.000000",
  "remaining": "25.000000",
  "address": null,
  "payer_wallet": null,
  "payout_address": "0x1111111111111111111111111111111111111111",
  "chain": { "id": "143", "name": "Monad" },
  "token": { "symbol": "USDC", "address": "0x754704Bc059F8C67012fEd69BC8A327a5aafb603", "decimals": 6 },
  "expires_at": "2026-09-06T13:00:00Z",
  "created_at": "2026-09-06T12:00:00Z",
  "...": "…"
}
    • deposit_url is what you give the payer.
    • address is null. The one-time address exists only after the payer signs from the wallet they will pay from. Never quote an address before then; a deposit_request.ready webhook reports the moment it exists.
    • Expiry defaults to 24 hours. Pass expires_in in seconds or an RFC 3339 expires_at; the window is 10 minutes to 366 days.

  3. Share the link

    Send deposit_url to the payer. If the request carried a payer.email, Payday has already emailed it to them. The hosted checkout shows the request, the network and exact token, the amount still due, the one-time address and QR once the payer has signed, a deadline countdown, and live finalized status. It can also send the transfer from a connected wallet in the page.

    The link is open by design: anyone holding it can read the request and pay it. It carries no merchant data, so nothing about your payout wallet, metadata, or policy assertions is exposed.

  4. Track settlement

    Read the request whenever you like, or long-poll so a screen updates the moment something changes. For automation, register a webhook instead and let Payday tell you.

    Shell
    curl -fsS "$API/v1/deposit-requests/dr_0198f80c-…?wait_for=change&timeout=30" \
  -H "Authorization: Bearer $PAYDAY_API_KEY" \
  | jq '{status, address, received, settlement_tx_hash}'

    A normal deposit moves awaiting_deposit → deposited → settled, with partially_deposited in between when transfers arrive in pieces. Payday credits only finalized transfers, so a payer's wallet may show a confirmed transaction a little before received changes.

  5. Download the Proof of Payment

    Once settled, every request yields a JSON proof tying the exact document to the payer's wallet, the one-time address, the transfers that paid it, and the settlement transaction. It verifies offline without trusting Payday. Keep it with your records.

    Shell
    curl -fsS "$API/v1/deposit-requests/dr_0198f80c-…/proof" \
  -H "Authorization: Bearer $PAYDAY_API_KEY" > proof.json

Next#

  • Verify the payer with an emailed code, or open the checkout from your own application for a user it has signed in.
  • Register a webhook so your system credits the deposit without polling.
  • Attach a PDF for an itemised breakdown; its hash is committed into the address.
  • Recipes walk through complete integrations.