DuckyPayDocs
ENTH

Quickstart

Accept your first test payment on Polygon Amoy in about 15 minutes — no real funds, no contracts to deploy.

Before you start#

You need a DuckyPay account (free, email verification only) and any EVM wallet you control — that wallet is where your money will arrive. Everything below runs against the Polygon Amoy testnet with test tokens, so nothing here can touch real funds.

The five steps#

  1. Create a project and connect your payout wallet

    Sign up at app.duckypay.co and create a project. Then set the project’s payout wallet — the address that receives every payment. You verify ownership by signing a message with that wallet (DuckyPay never asks for keys, only a signature).

    Charges are refused until a payout wallet is set — there is nowhere for the money to go.

  2. Copy a test API key

    In the project’s API keys page, copy the test key (dp_test_…). Test keys can only create charges on testnets, and live keys only on mainnets — you cannot mix them up. Details in Authentication.

  3. Create a charge

    One authenticated call mints an invoice and returns a hosted checkout URL. Amounts are strings in the token’s smallest unit — 5000000 is 5 USDC at 6 decimals (the @duckypay/node SDK ships toBaseUnits("5", 6) so you never do this math by hand).

    terminal
    curl https://api.duckypay.co/v1/invoices \
  -H "x-api-key: $DUCKYPAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "chainId": 80002,
    "amount": "5000000",
    "paymentMode": "both",
    "reference": "order_1001"
  }'
    201 response (trimmed)
    {
  "success": true,
  "data": {
    "invoiceId": "0x2b7e…c4a1",
    "chainId": 80002,
    "mode": "both",
    "checkoutUrl": "https://pay.duckypay.co/c/0x2b7e…c4a1",
    "depositAddress": "0x9F62…7EBB",
    "token": "0x34D9…d14A",
    "amount": "5000000",
    "feeBps": 0,
    "deadline": "1789552800",
    "intent": { "…": "signed PaymentIntent for wallet mode" },
    "signature": "0x…"
  },
  "error": null
}

  4. Pay it on the hosted checkout

    Open checkoutUrl in a browser. Because the charge was created with paymentMode: "both", the checkout offers two rails: connect a wallet on Amoy, or send the test token to the per-invoice deposit address shown. For gas, grab free Amoy POL from the official Polygon faucet.

  5. Confirm the payment

    Poll the lightweight status route until it flips to paid — or better, register a webhook and receive a signed invoice.paid event with your reference echoed back.

    terminal
    curl https://api.duckypay.co/v1/charges/0x2b7e…c4a1/status \
  -H "x-api-key: $DUCKYPAY_API_KEY"

# → { "success": true, "data": { "invoiceId": "0x2b7e…c4a1", "status": "paid" }, "error": null }

    Once the on-chain transaction confirms, the funds are already in your wallet; the status usually catches up within a couple of minutes.

Where to go next#

  • Webhooks — fulfil orders automatically with signature-verified events.
  • Payment modes — choose between wallet, transfer, or both for real traffic.
  • Go-live checklist — flip from Amoy test money to Polygon mainnet.