Platform

How it works behind the API

A payment request enters at the edge, becomes an event on a queue, is spread across workers and comes back to you as a webhook. Five short parts.

01

Infrastructure layers

A request passes five layers from the edge to the vault. Each layer has one job.

Cloudflare and CloudFront take the request, filter traffic and pass it on to the API.

Production and sandbox are separate

The two environments run on separate databases. Sandbox keys contain _test_, so test data never mixes into production.

Region
Frankfurt (eu-central-1)
Production
Separate database
Sandbox
_test_Separate database
Card vault
Not reachable from the internet

02

Event capture

Every payment change is written to a queue as an event. An event that cannot be processed is not dropped, it is retried.

  1. API

    Saves the change

  2. Event queue

    Event is written

  3. General worker

    Takes batches

  4. Webhook queue

    Send order

  5. Webhook sender

    Signs and sends

  6. Your endpoint

    Your server

If an event fails
An event that is received 5 times without being processed is set aside in the dead-letter queue. It is not deleted.
  1. 1 receive
  2. 2 receive
  3. 3 receive
  4. 4 receive
  5. 5 receive
  • Goes back to the queue
  • Set aside in the dead-letter queue

Messages in the queue and in the dead-letter queue are held for 4 days.

A scheduler retriggers deliveries that are still waiting every 15 minutes.

03

Consistency

You can resend a request even if it got lost on the network. A request with the same Idempotency-Key returns the first result.

Send the same request twice

The first request creates the payment, repeats return the first result.

POST /v1/payments

Idempotency-Key: order_8841

Requests sent 0Payments created 0
  • No request sent yet

What goes into the fingerprint

Besides the key, the request itself is compared. Only the fields that define the payment go into the fingerprint.

Compared

  • Payment
  • Card or saved method
  • Routing strategy

Left out

  • CVV
  • Name
  • IP address
  • Lease time 2 min

    While the first request runs the key stays locked, so a concurrent second request cannot open a second payment.

  • Key length 1-255

    Any value you generate. The SDK retries a POST only when a key is present.

04

Webhook system

If your endpoint fails, delivery is not dropped. It is retried 10 times at growing intervals and every attempt carries the same body.

Events you can subscribe topayment.createdpayment.processingpayment.succeededpayment.failedcharge.createdcharge.capturedcharge.failedrefund.createdcheckout_session.createdcheckout_session.failedcustomer.createdcustomer.updated
delivery log
  • POST /hooks/hsrcpay500attempt 1
  • retry in 5 s
  • POST /hooks/hsrcpay200attempt 2
  • SUCCEEDED

The wait grows after each attempt and the body does not change.

  1. 5s
  2. 10s
  3. 15s
  4. 30s
  5. 1m
  6. 2m
  7. 5m
  8. 10m
  9. 30m
  10. 1h

05

Automatic scale-out

There is no fixed server. Copies start as load grows and queues absorb sudden spikes.

The queue absorbs the spike

In a spike, work waits in the queue and workers take it at a steady pace.

Incoming workProcessed work

Schematic, not a measurement.

Four things that make it scale

None of them needs tuning on your side.

  • A copy per request

    Requests go to copies that start when needed, not to a fixed server. A copy that sits idle shuts down.

  • Queues act as a buffer

    In a spike, work waits in the queue and workers take it in turn. A full queue does not lose work.

  • Account quota

    Every account has a quota ceiling so one account's load does not slow down the others.

  • Controlled pace

    Worker concurrency is kept limited on purpose, so the database and payment providers are not overloaded.

Details are in the docs

See the docs pages for idempotency, webhook signatures and event types.