Ashish Pitrodafield notes
All plates

Field guide Plate 04

Integrations

Payment gateways, authentication, webhooks, and syncing data between two systems that were never designed to know about each other. The work is rarely difficult; it is detailed, and the details are where money goes missing.

— making systems agree

I

Where it’s found

who this is for

You need to take money

and want it done so that a failed card, a duplicate submit and a webhook arriving twice all end with the right amount charged exactly once.

Two systems hold the same data

and have started to disagree. Sync is easy to write and hard to write correctly, and the difference only shows up under load or after an outage.

Someone else’s API changed

and yours broke quietly. Integrations need to fail loudly and recover on their own, which is a design decision made before the first request is written.

II

Field marks

what the work actually is

  1. Payment gateways

    Checkout, subscriptions, refunds and the webhook side. Idempotency taken seriously, because the alternative is charging someone twice and finding out from them.

  2. Authentication

    OAuth, SSO, API keys and token refresh, with the failure paths handled — expired tokens and revoked access are normal events, not exceptions.

  3. Webhooks, both directions

    Receiving them verified, deduplicated and queued rather than processed in the request. Sending them with retries and a dead-letter path.

  4. Data sync

    Between a CMS and a CRM, a shop and an accounting system, an application and a warehouse. With a reconciliation job, because drift is not a possibility, it is a certainty.

  5. Knowing when it breaks

    Logging, alerting and a way to replay what failed. An integration nobody is watching is an outage you find out about from a customer.

III

Behaviour

how it runs

  1. 01Read the docs

    Theirs and yours. Most integration surprises are documented somewhere nobody read.

  2. 02Map the failures

    What happens on a timeout, a duplicate, a partial success. Agreed before anything is built.

  3. 03Build against sandbox

    With the awkward cases exercised, not just the happy path.

  4. 04Watch it in production

    Alerting from day one, and a short window after launch to answer for it.

IV

What it costs

what decides the price

The provider decides most of it. A well-documented modern API with a sandbox is a predictable job. A legacy endpoint with no sandbox, no documentation and a support queue measured in days is a different quote, and I would rather say that at the start.

Defined integrations are quoted fixed. Where the other end is an unknown, the first step is a short paid investigation of it before anyone commits to a number.

V

Questions

the ones I get asked

Do you handle card details?
No, and neither should your server. Card data goes to the gateway directly from the browser, which keeps you out of the part of PCI compliance you do not want to be in.
The other side has no sandbox. Now what?
Then the first piece of work is building one — a stub that behaves like their documentation says they do. It costs a little up front and saves the testing being done on live data.
Can you fix an integration someone else wrote?
Often, and usually the problem is the same one: it assumes every request succeeds first time. Adding retries, idempotency and a replay path is far cheaper than rewriting it.

Send a note

Tell me what you have, what is wrong, and what it should do instead. I will tell you honestly whether I am the right fit.

Write to me or read the other plates