Chapter Ten · Talking to Other Services
Talking to Other Services
Payrail is the one system Stagedoor depends on and does not control, and everything Chapter 7 built is applied here to that one neighbour. Five topics build the outbound client with its three timeouts and its derived key, receive Payrail's webhook without trusting it, write the nightly job that found 14 orders Payrail had settled and Stagedoor had not, turn checkout into a saga with a compensation for every step, and pin the contract on both sides so a change is caught by a test rather than a buyer.
One outbound call and one webhook back, across a network Stagedoor does not own, to a system whose release calendar Stagedoor does not set. POST /v1/charges answers in 400 milliseconds at P50 and is given 3 seconds, and a call that gets no answer in 3 seconds may or may not have charged the card. payment.settled comes back signed, at least once, and not in order. Between those two facts sit every mechanism of Chapter 7 with a real neighbour on the other end: the timeout, the retry that is safe only because the key is order-{public_id}, the breaker, the outbox, and the honest answer to the buyer when the outcome is unknown.
No wound from the spring on-sale closes here; the double charge closed in Chapter 7, and this chapter is what keeps it closed when the failure is on Payrail's side of the wire. What opens instead is a number nobody had counted: at the end of the month, 14 orders sat in pending for payments Payrail had settled, one buyer each, found by 14 support tickets. Six webhooks lost in a Payrail outage, four jobs dead-lettered by a seat label, three events recorded and never enqueued, one host with a clock 6 minutes fast. Every mechanism had worked as designed, and every one assumed a message would eventually arrive. Reconciliation is the job that stops assuming and asks, and it is the last line of the book's spine: when two systems disagree, one of them goes and looks.
The chapter is Payrail's side of Stagedoor, done properly. The client is one class with every policy in it and a fake the tests can swap in. The webhook is verified over raw bytes, deduplicated by event id, acknowledged in 50 milliseconds and applied through the order's state machine. The nightly job walks both directions and fixes only what has one possible fix. Checkout becomes a saga whose state is a column and whose steps are each safe to repeat. And the contract with the scanner and with Payrail is generated, pinned, diffed and tested, so that the two directions of dependence are promises a machine checks.