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.
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.
API
Saves the change
Event queue
Event is written
General worker
Takes batches
Webhook queue
Send order
Webhook sender
Signs and sends
Your endpoint
Your server
- 1 receive
- 2 receive
- 3 receive
- 4 receive
- 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
- 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.
- 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.
- 5s
- 10s
- 15s
- 30s
- 1m
- 2m
- 5m
- 10m
- 30m
- 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.
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.