Deposit requests

Create a deposit request

POST/v1/deposit-requests

Issues a deposit request.

API key · or dashboard session.

Request

Shell
curl -fsS "$API/v1/deposit-requests" \
  -H "Authorization: Bearer $PAYDAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: INV-1042" \
  -d '{
    "amount": "10.50",
    "payout_address": "0x1111111111111111111111111111111111111111",
    "issuer": { "name": "Acme LLC", "email": "billing@acme.example" },
    "payer": { "name": "Customer Inc", "email": "ap@customer.example" },
    "heading": "March retainer",
    "reference": "INV-1042",
    "notes": "Net 30. Thank you.",
    "payer_policy": { "mode": "verified_email", "expected_email": "ap@customer.example" },
    "customer_id": "cus_0198f80c-1111-7dc1-a369-90556a64f700",
    "issuer_id": "iss_0198f80c-2222-7dc1-a369-90556a64f700",
    "expires_in": 3600,
    "metadata": { "po": "PO-77" }
  }'

Response

201 Created
{
  "id": "dr_0198f80c-8d2f-7dc1-a369-90556a64f700",
  "deposit_url": "https://payday.sh/pay/dr_0198f80c-8d2f-7dc1-a369-90556a64f700",
  "status": "awaiting_deposit",
  "chain": { "id": "143", "name": "Monad" },
  "token": { "symbol": "USDC", "address": "0x754704Bc059F8C67012fEd69BC8A327a5aafb603", "decimals": 6 },
  "currency": "USDC",
  "address": null,
  "address_explorer_url": null,
  "payout_address": "0x1111111111111111111111111111111111111111",
  "payer_wallet": null,
  "recovery_address": null,
  "wallet_bound_at": null,
  "amount": "10.500000",
  "amount_base_units": "10500000",
  "received": "0.000000",
  "received_base_units": "0",
  "remaining": "10.500000",
  "remaining_base_units": "10500000",
  "fee_amount": "0.000000",
  "fee_amount_base_units": "0",
  "net_amount": "10.500000",
  "net_amount_base_units": "10500000",
  "issuer": { "name": "Acme LLC", "email": "billing@acme.example" },
  "payer": { "name": "Customer Inc", "email": "ap@customer.example" },
  "heading": "March retainer",
  "reference": "INV-1042",
  "notes": "Net 30. Thank you.",
  "metadata": { "po": "PO-77" },
  "customer_id": "cus_0198f80c-1111-7dc1-a369-90556a64f700",
  "issuer_id": "iss_0198f80c-2222-7dc1-a369-90556a64f700",
  "payer_policy": { "mode": "verified_email", "expected_email": "ap@customer.example" },
  "attachment": null,
  "verification_completed_at": null,
  "likely_unsolicited_at": null,
  "created_at": "2026-09-06T12:00:00Z",
  "updated_at": "2026-09-06T12:00:00Z",
  "expires_at": "2026-09-06T13:00:00Z",
  "deposited_at": null,
  "deposited_at_block": null,
  "settled_at": null,
  "settled_block": null,
  "expired_at": null,
  "cancellation_requested_at": null,
  "settlement_tx_hash": null,
  "settlement_explorer_url": null,
  "attention": null,
  "transfers": [],
  "as_of": { "block": "98765000", "at": "2026-09-06T11:59:58Z" },
  "indexer_freshness": {
    "last_indexed_block": "98765000",
    "last_finalized_block": "98765000",
    "cursor_updated_at": "2026-09-06T11:59:59Z"
  },
  "self_settlement": null,
  "attribution": { "version": 2, "hash": "0x…" }
}

Minimal body: amount, issuer_id, customer_id, payer_policy. Unknown fields are rejected. Text fields reject control characters. Every immutable field participates in idempotency, including the attachment's hash.

address, payer_wallet, recovery_address, wallet_bound_at, and self_settlement are null until the payer's wallet attestation is accepted, signalled by deposit_request.ready. Recovery is not a request field; recovery_address is always the attested wallet.

Headers

Idempotency-Keystringrequired
1–255 bytes.

Body

amountstringrequired
Positive USDC decimal; at most six fractional digits. Settled exactly.
payer_policyobjectrequired
{"mode":"permissionless"} · {"mode":"verified_email","expected_email"} · {"mode":"merchant_session","payer_reference"}. expected_email is trimmed and lowercased. payer_reference: 1–128 printable bytes, no whitespace, case preserved. Assertions are rejected on other modes.
payout_addressstring
Nonzero EVM address. Required unless issuer_id names an identity with a saved payout address, whose first address is used.
issuerParty
name 1–255 bytes; email 3–254 bytes; details ≤4,000 bytes. Required unless issuer_id is given. Inline wins.
payerParty
Same shape. Required unless customer_id is given. Inline wins. payer.email receives the issued request by email, except under merchant_session.
issuer_idiss_ id
Stored immutably on the request. Supplies issuer and payout_address when omitted.
customer_idcus_ id
Stored on the request. Supplies payer when omitted; the request keeps its own snapshot.
headingstring
≤200 bytes. Visible to the payer before verification.
referencestring
≤128 characters. Exact-match filter on list.
notesstring
≤4,000 bytes. Visible to the payer after verification.
attachment_idatt_ id
A finalized attachment. One per request.
expires_ininteger
Seconds. Exclusive with expires_at. Default 86,400; range 600 to 31,622,400.
expires_attimestamp
RFC 3339. Same range.
metadataobject
≤16 keys; ≤512 encoded bytes per value. Returned on reads and webhooks. Merchant-only.
chain_id, token_addressstring
Deployment overrides. Must equal the environment's values when present.

Response

DepositRequest. Under merchant_session, also client_secret and client_secret_expires_at, once.

Status codes

  • 201Issued.
  • 200Idempotent replay. Idempotency-Replayed: true.
  • 400invalid_request Shape, unknown field, type, or control character. Message names the field.
  • 400invalid_amount Syntax, precision, or sign.
  • 400missing_idempotency_key Header absent.
  • 404customer_not_found / issuer_not_found Not owned by the account.
  • 409idempotency_conflict Key reused with a different document.
  • 409attachment_not_ready Attachment not finalized, rejected, or expired unused.
  • 409attachment_already_attached Attachment belongs to another request.
  • 409account_contact_required Account has no verified email. Re-authenticate in the dashboard.
  • 422unsupported_chain / unsupported_token Override not served by the environment.