A valid request URL is required to generate request examples{
"received": true,
"outcome": "<string>"
}{
"error": {
"code": "invalid_signature"
}
}{
"error": {
"code": "payload_too_large",
"message": "<string>"
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "not_settled"
}
}Where the payment provider delivers
NOT AN ENDPOINT YOU CALL. The payment provider posts here, and this is the step that turns a settled payment into admission and a provisioned device, and a reversal back out again.
NO CREDENTIAL OF OURS AUTHENTICATES IT, because the sender holds none. A delivery is authenticated by a signature over the raw body, checked before the body is parsed and before anything is recorded. No Authorization header is read here and sending one changes nothing, which is why this route sits outside /v1 rather than inside it.
WHAT THE STATUS CODES MEAN, which is the real contract with the sender. 200 is settled: the transaction that recorded the event committed before the answer was sent, so the delivery is finished. 400 is a delivery that was not authentic or not readable, and nothing was recorded. 5xx is ours to fix and the delivery should be repeated; there is deliberately no retry inside this process. A repeat of an event already recorded settles again rather than applying twice.
A body over 262144 bytes is refused as it streams, before any of it is held in memory. That is tighter than the service wide cap the 413 below describes, and it is the one that applies here.
IT IS ABSENT ON A DEPLOYMENT THAT HAS NO SIGNING SECRET CONFIGURED. An endpoint that accepts bodies it cannot authenticate is worse than a 404, so such a deployment does not mount it at all.
Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404.
A valid request URL is required to generate request examples{
"received": true,
"outcome": "<string>"
}{
"error": {
"code": "invalid_signature"
}
}{
"error": {
"code": "payload_too_large",
"message": "<string>"
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "not_settled"
}
}Body
The provider's own event envelope, byte for byte as it sent it. Read only once the signature matches.
The provider defines this shape. Fields beyond the ones named here travel through and are ignored.
The provider's id for this event. The key the delivery is recorded under, and what makes a repeat recognisable.
The provider's event type. A type this service does not act on is recorded and settled, and no field is read off its object.
Seconds since the epoch, as the provider stamped it. The only ordering input used, so it is never defaulted to our own clock: an envelope without it is refused rather than guessed at.
Show child attributes
Show child attributes
Response
Settled, so the delivery is finished. Also the answer for an event this service does not act on, for a repeat of one already recorded, and for a reversal that can never be attributed to an organisation: repeating that one cannot add a reference the object does not carry, so it raises an operator alarm here instead of being handed back for redelivery.