Quickstart¶
This guide takes you from zero to a successful test charge. It should take about five minutes.
Before you begin¶
You need a sandbox API key. Sandbox keys start with sk_test_ and only ever touch simulated money. Keep them out of source control and out of client-side code.
1. Verify your key¶
A quick read-only call confirms the key works and the network path is open.
A 200 OK with your account object means you're ready. A 401 means the key is missing or wrong — see Authentication.
2. Create a charge¶
This charges a test card 20.00 USD. Amounts are always in the currency's smallest unit, so 20.00 USD is 2000.
curl https://api.pudgypay.dev/v1/charges \
-H "Authorization: Bearer $PUDGY_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d amount=2000 \
-d currency=usd \
-d source=tok_visa \
-d "description=Quickstart test charge"
The Idempotency-Key header is optional here but you should treat it as mandatory in real code. It makes the request safe to retry without double-charging — see Idempotency.
A successful response:
{
"id": "ch_3Nf8k2eZvKYlo2C1",
"object": "charge",
"amount": 2000,
"currency": "usd",
"status": "succeeded",
"paid": true,
"description": "Quickstart test charge",
"created": "2026-05-30T17:42:11Z"
}
3. Retrieve the charge¶
Use the id from the previous response to read the charge back.
curl https://api.pudgypay.dev/v1/charges/ch_3Nf8k2eZvKYlo2C1 \
-H "Authorization: Bearer $PUDGY_KEY"
What just happened¶
You authenticated with a bearer token, created a resource with a typed JSON response, and read it back by ID. Every other resource in the API — customers, refunds, payouts — follows the same pattern.
Next steps¶
-
Make it production-grade
Add idempotency keys and structured error handling.
-
React to events
Stop polling. Let Pudgy notify you when a charge settles or fails.
-
Build a real flow
Walk through accepting a one-time payment from a customer.