Quickstart

This guide takes you from a fresh sandbox key to a successful test payment, then to the 3-D Secure flow.

Prerequisites

You'll need:

• An HTTP client (curl, Postman, or your language's HTTP library)
• A Paayed dashboard account
• A basic understanding of JSON

1. Get your API key

Open Developers → API keys in the dashboard and create a sandbox key. It's shown once — copy it now. It looks like this:

pyd_secret_test_4f2c9d8e1f7a91RSdSRRzr8PMRU...

Sandbox and production keys live on the same account. You can create a production key right away too — it just won't authenticate until your account goes live.

2. Take your first payment

curl -X POST 'https://gateway.sandbox.paayed.com/v1/payments' \
  -H 'Authorization: Bearer pyd_secret_test_your_key_here' \
  -H 'Idempotency-Key: 5f1e6a6c-9d3f-4a2f-9a1e-2b7c1d9e4f88' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 42.50,
    "currency": "GBP",
    "capture": true,
    "reference": "ORDER-10023",
    "payment_method": {
      "type": "card",
      "card": {
        "number": "4242424242424242",
        "expiry_month": 12,
        "expiry_year": 2029,
        "cvc": "123",
        "holder_name": "A Cardholder"
      }
    }
  }'

You should get back:

{
  "id": "pay_01JBQ7X2F9KDNW3M8T",
  "object": "payment",
  "status": "succeeded",
  "amount": 42.50,
  "amount_captured": 42.50,
  "currency": "GBP",
  "reference": "ORDER-10023",
  "livemode": false
}

Idempotency-Key is mandatory on every write — a request without it is rejected with 400.

3. Try 3-D Secure {#test-cards}

Sandbox outcomes are deterministic, driven by the card number:

Send the 4000 0000 0000 3220 card and you'll get back status: "requires_action" with a next_action.redirect.url. Send the cardholder's browser there; the outcome arrives both as a webhook and on your return_url.

4. Refund it

curl -X POST 'https://gateway.sandbox.paayed.com/v1/payments/pay_01JBQ7X2F9KDNW3M8T/refunds' \
  -H 'Authorization: Bearer pyd_secret_test_your_key_here' \
  -H 'Idempotency-Key: 3d70a1b2-...' \
  -H 'Content-Type: application/json' \
  -d '{ "reason": "requested_by_customer" }'

Refunds are asynchronous — the response comes back status: "pending" and resolves to succeeded or failed via webhook.

5. Explore the API reference

Head to the API Reference for every endpoint, request schema and response format, with code samples in cURL, JavaScript, Python and more.

Next steps