Payment & API Integrations

What an integration actually is

An integration is your app using another service to do something it can't do on its own: take a payment, send an email, count visitors. Your app sends a request to the service's API, and for anything that happens later, such as a payment clearing, the service sends a message back to your app, called a webhook. Every integration in these guides is one or both of those.

If the words API and webhook are new, What Is an API? and What Is a Webhook? explain them in plain language first.

Why your AI may build it the unsafe way first

Asked to "add payments" or "send an email when someone signs up", an AI coding agent often reaches for the quickest version that works in a demo, and the quickest version can put the call, and its secret key, in the page itself. It works in preview, so nothing looks wrong. The problem is that anything in the browser can be read by anyone who opens the page, so a key there is a key anyone can copy and use.

The fix is to say what you want before any code is written: the call goes through a backend function, the key is stored as a secret, and the page only talks to your own backend. Why you can't put an API key in the frontend explains the reasoning, and third-party API best practices covers the rest of the plan: time limits, retries, rate limits and what to log.

Payments: the return page isn't proof

A payment is the integration where the three rules matter most. The customer pays on the gateway's own page, then comes back to yours, but arriving back on your "thank you" page doesn't prove anything was paid; anyone can open that address. The proof is the gateway's webhook, checked on your backend, with the amount matched against the order. Card gateways and Instant EFT work the same way here. How to add a payment gateway explains the whole flow, with South African gateways as examples, and ends with the prompt to give your AI.

Email and analytics: where POPIA comes in

Both of these handle your visitors' personal information, so both carry a POPIA question as well as a technical one. Email is sent from your backend through an email service, and your domain has to be set up so inboxes trust it; sending email from your app covers both halves. Analytics tools set identifiers on a visitor's device, so consent has to come before tracking; Google Analytics and POPIA explains why, and how to check that nothing loads before a visitor agrees.

What isn't possible

• There's no safe place for a secret key in the browser. Hiding it, splitting it or encoding it doesn't help; if the page can use it, a visitor can find it.
• Your AI doesn't know a service's current rules unless you show it the documentation. Services change their fields and signing rules, and an AI working from memory can be out of date.
• You can't make another service reliable. You can only decide what your app does when it's slow or down.
• Test mode isn't the same as live. Most payment and email services offer a test mode, and you should use it first, but check the live setup once more with real keys before launch.

A prompt before you add any integration

Use this before the first line of code for any new service. It asks for a plan you can check against the three rules above.

I'm not a coder. I want my app to connect to [name
of the service] so that [what it should do]. Here is
its documentation: [paste it or link it].

Don't write any code yet. Give me a plan that says:
1. Which keys or secrets this needs, where each one
   is stored, and confirmation that none of them is
   ever sent to the browser.
2. Which parts run in the backend and which in the
   page, and why.
3. If the service sends messages back to my app
   (a webhook), how each one is checked before my
   app acts on it.
4. What happens if the service is slow, fails, or
   sends the same message twice.
5. How I can test it without real money, real
   customers or real emails.

If the documentation doesn't answer something, say
so instead of guessing.

What to check in the AI's answer

• No key reaches the browser. If the plan puts a secret in a page, a component or anything the browser loads, ask it to move it.
• Webhooks are checked first. The plan should verify each incoming message before it changes an order, an account or anything else.
• Failures have answers. Look for what the user sees on a timeout, and how a repeated message is stopped from doing the same thing twice.
• There's a way to test it safely. A test mode, test keys or your own email address, not "try it with a real payment".