Introduction — Paayed

Paayed's public payments API lets a developer take a card payment against a Paayed merchant, using credentials created entirely by them — no onboarding call required to get started. The API is shaped like Stripe's, so an integrator moving from Stripe should find the translation mechanical. The acquirer behind it is never visible.

How it works

Create a secret key in the Paayed dashboard. It is shown once and stored hashed.
Send one request to POST /v1/payments with the customer, the order items, the card and an idempotency key.
Receive a payment object whose status is succeeded, declined, or requires_action when 3-D Secure is needed, with a redirect to complete it.
Receive later changes — authentication completing, a refund settling, a subscription charge — as signed webhooks, and read them back from the events endpoint if a delivery is missed.

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

{
  "id": "pay_01JBQ7X2F9KDNW3M8T",
  "object": "payment",
  "status": "succeeded",
  "amount": 42.50,
  "currency": "GBP",
  "livemode": true
}

No SDK required. Any HTTP client will do.

What you can do

Take payments

Create, capture, cancel and refund card payments. Raw card, hosted page, or client-side tokenisation, depending on your PCI posture.

Run subscriptions

Store a card once with the cardholder present, then charge it on a fixed schedule as a merchant-initiated transaction.

Manage customers

Customer records and their stored payment methods, shared across payments, hosted sessions and subscriptions.

React to events

Signed webhooks for every state change, retried for about two days, with a 30-day event log as a backstop.

Why it's shaped this way

Familiar if you've integrated Stripe

Most of the contract maps to Stripe's field for field: the same idempotency header, the same webhook signing scheme, the same event-log recovery mechanism. Where a name differs — our identifier prefixes, our own decline code taxonomy — it's because the Stripe name carried history we don't need. See the migration guide in the API reference for a full field-by-field comparison.

Strict about money and idempotency by default

Amounts travel as decimal major units (42.50, not 4250), validated against the currency's exact decimal places on the way in. Every write requires an Idempotency-Key; a retried timeout can't take a payment twice.

Sandbox and production on the same account

Create a sandbox key immediately and start building. Create a production key at the same time — it's usable the moment your account goes live, so nothing changes on the day you switch over.

The acquirer is never named

Every response is mapped into a Paayed-owned taxonomy before it reaches you. No field, error code, status string or webhook payload identifies our processing partner.

Get started

Get your API key

Open Developers → API keys in the dashboard and create a sandbox key. It works immediately against the simulator.

Take a test payment

POST /v1/payments with one of the sandbox test cards. Try 4000 0000 0000 3220 to see the 3-D Secure flow.

Handle 3-D Secure

Send the cardholder's browser to next_action.redirect.url when a payment comes back requires_action, and read the final outcome from the webhook or a GET on return.

Set up webhooks

Register an endpoint for payment.succeeded, payment.declined and refund.succeeded at minimum. Verify every signature before you trust the payload.

Go live

Create a production key any time — it authenticates once your merchant account is active, with no other change to your integration.