What a reliable API integration needs: payments, ERP, CRM and bookings

A reliable integration with a payment provider, ERP, CRM or booking system needs eight things: safe authentication, idempotent requests, timeouts and retries with backoff, verified webhooks, a plan for API versions, logs and alerts, regular reconciliation, and documentation. Most integration failures come from assuming the network always works. The design has to decide in advance what happens when a call times out, arrives twice or never arrives at all.

#Authentication and secrets

Every integration starts with credentials, and most security problems in integrations start there too. The common patterns are an API key sent in a header, or OAuth 2.0, where your system exchanges a client ID and secret for a short-lived access token.

• Keep secrets out of the code. Store keys in environment variables or a secrets manager, never in the Git repository. A key that was ever committed should be treated as leaked and rotated.
• Separate test and live credentials. Payment providers and many ERPs offer a sandbox. Use it for development and automated tests, and make it impossible for a test environment to reach live credentials.
• Ask for the narrowest permissions. If the integration only reads orders, the key should not be able to issue refunds.
• Handle token expiry. Refresh OAuth tokens before they expire, and when a call returns 401, refresh once and retry once. Anything beyond that is a real error.
• Plan the rotation. Know how to replace a key without downtime, and who has the right to do it.

#Idempotency: making a repeated request safe

Imagine your shop sends "charge this card" to the payment provider, and the connection drops before the answer arrives. The charge may or may not have happened. If you retry blindly, the customer may be charged twice. If you do not retry, the order may stay unpaid even though the money moved.

Idempotency solves this. You generate a unique key for each business operation, for example one per order payment attempt, and send it with the request. If the provider receives the same key twice, it returns the original result instead of performing the operation again. Stripe and several other payment APIs accept an Idempotency-Key header for exactly this reason.

When an API has no such feature, you build the same guarantee yourself:

• Record the operation in your own database with a unique ID before calling the external system.
• Send your ID as the external reference, such as the order number on an ERP invoice.
• Before a retry, ask the external system whether an object with that reference already exists.

The same rule applies in the other direction. Anything your system receives from outside, whether a webhook or an imported file, should be safe to process twice. A unique constraint on the external event ID in your database is often enough.

#Timeouts, retries and backoff

Every outgoing call needs an explicit timeout for connecting and for reading the response. Some HTTP clients wait indefinitely by default, and a single slow partner can then tie up all your workers and take your own site down with it.

Retry only the failures that can succeed on a second attempt:

Response	Retry?	What to do
Network error or timeout	Yes, with an idempotency key	Back off and try again
5xx server error	Yes	Back off and try again
429 Too Many Requests	Yes	Wait as long as the Retry-After header says, if present
400 or 422 validation error	No	Fix the data and alert someone
401 or 403	Once, after refreshing the token	Then treat it as a configuration error

Use exponential backoff with a little randomness (jitter), so that hundreds of failed jobs do not all retry in the same second. Cap the number of attempts. After the last one, move the job to a failed queue where a person can see it and replay it.

Where possible, make external calls from a background queue instead of during the customer's page request. The customer sees "order received" at once, and the ERP sync can retry for as long as it needs to without anyone waiting on a spinner.

#Webhooks: verify, acknowledge, then process

Webhooks are how payment providers, booking platforms and CRMs tell you something changed. They arrive over the public internet, so treat each one as untrusted until verified.

• Check the signature. Most providers sign each webhook, typically with an HMAC of the raw request body and a shared secret. Compute the signature over the raw body before any JSON parsing, and compare it in constant time.
• Reject old messages. If the signature includes a timestamp, refuse events outside a short window to block replayed requests.
• Answer fast. Store the event, return a 2xx response, and do the real work in a queue. Slow responses make the provider assume failure and send the event again.
• Expect duplicates and wrong order. Webhooks can arrive twice, late, or out of sequence. Store the event ID, and when order matters, fetch the current state of the object from the API instead of trusting the event body.
• Do not rely on webhooks alone. If the endpoint was down for an hour, some events may never be redelivered. Reconciliation, described below, catches what webhooks miss.

#Versioning, logging and alerts

External APIs change. Many providers let you pin the API version your integration was built against, and you should. Subscribe to the provider's changelog or deprecation notices, and put all calls to each provider behind one adapter module in your code, so that an API change touches one place instead of fifty.

If you publish an API of your own for partners or a mobile app, version it from the first release, describe it with an OpenAPI document, and keep the old version running until clients have moved.

For logging, record every outgoing request and incoming webhook with a correlation ID, the endpoint, the status code and the duration. Mask card data, personal data and secrets. When a customer calls about a missing booking, these logs let you answer in minutes.

Logs only help if someone reads them, so add alerts for the signals that matter:

• The error rate for a provider rises above its normal level.
• The failed job queue is not empty.
• No webhooks have arrived in a period when some should have.
• Reconciliation finds mismatches.

#Reconciliation and documentation

Reconciliation is a scheduled job that compares your records with the other system and reports differences. Examples: payments captured by the provider against orders marked as paid, stock levels in the ERP against stock in the shop, bookings on the platform against bookings in your calendar. Run it daily or more often, send the report to a named person, and fix the causes, not only the individual records.

Documentation is what lets the next developer, or your own team in a year, keep the integration running. At minimum it should cover:

• Which systems are connected, in which direction, and what triggers each sync.
• A field mapping: which field in your system becomes which field in theirs, including units, currencies and time zones.
• Where the credentials are stored (never the values themselves) and how to rotate them.
• The retry policy and what to do when a job ends up in the failed queue.
• Sandbox accounts and the steps to run the integration tests.

If you are inheriting an integration someone else built, start with this list. The article on taking over a codebase another team built covers the wider handover.

#How PN Scripts can help

PN Scripts connects payment providers, booking systems, ERP and CRM through their APIs and webhooks, with retries, logs and alerts when a call fails. Every integration has automated tests and is documented for your team. You can see how this fits into a project on the web development page.