How to Add a Payment Gateway to Your AI-Built Website

How do online payments work?

Four parties are involved: the customer, your site (the pages they see), your server (the part that runs out of sight and keeps secrets) and a payment gateway. Your site sends the customer to the gateway to pay. The gateway then tells your server, in a signed message, whether the money came through, and your server checks it.

A payment gateway is a company that takes the payment on your behalf and pays the money out to your bank account. PayFast, Yoco and Peach Payments are South African examples that take cards and other methods; Ozow is an example built around Instant EFT, paying straight from the customer's bank account (Ozow calls it Pay by Bank). The names matter less than the pattern, because almost every gateway follows it.

The whole payment, in six steps

Steps 4 and 5 are two separate messages on two separate paths. Step 4 travels through the customer's browser. Step 5 goes straight from the gateway's server to yours, and the customer never sees it. Most payment code an AI writes on its first try handles step 4 and forgets step 5.

The "payment successful" page is not proof of payment

When the gateway sends the customer back to your site, the page they land on is only a web address opening in their browser. Anyone can type that address in without paying, and a customer who closes the tab too early never arrives at it at all, even though they paid. So the return page can say "thank you", but it must never be the thing that marks an order paid, unlocks a download or books a slot.

The notification is a webhook: a message one server sends to another when something happens. Each gateway has its own name for it (PayFast calls it an ITN, an Instant Transaction Notification), but the job is the same everywhere.

Three ways to connect a gateway, and what each needs

A payment link or button. You create a link in the gateway's dashboard and put it behind a button on your page. There's no code and nothing to build. The limit is that your site never finds out about the payment, so you match payments to orders by hand. That's fine for a few sales a week, and it breaks down once you have stock, bookings or downloads to release automatically.

A hosted checkout (a redirect). Your server creates the payment, the customer pays on the gateway's page, and the gateway notifies your server. This is the one this page teaches, and it's the right default for an AI-built site. Card numbers and bank logins never touch your site, so a mistake in your code can't leak them.

Payment fields inside your own page. Some gateways let the card form appear inside your page. It looks smoother, but there's more to get right and more for your AI to get wrong, because the card form now sits on your page instead of the gateway's. Start with a hosted checkout and move only if you have a real reason.

Some AI website builders now offer built-in payments through an international provider. That can be the quickest route. Before you rely on one, check whether it can pay out to a South African business and bank account, which payment methods your customers would get, and who the customer's bank statement shows as the seller.

Why the keys and the checking live on your server

A gateway gives you two kinds of key. A public key or merchant ID only identifies your account. A secret key, passphrase or webhook secret proves a request really came from you, or a notification really came from the gateway. Anything in the code that runs in the visitor's browser can be read by anyone who opens the browser's developer tools. So the secret has to sit on a server, where visitors can't see it. Our guide to why an API key can't go in frontend code explains this in more depth.

That's why a hosted checkout, or anything beyond a plain payment link, needs a backend, the part of your app that runs on a server. If your AI website builder set up a database and logins for you, it almost certainly gives you somewhere to run server code too, often called server functions, edge functions or backend functions. Ask your AI where yours run and where it stores secrets. If the answer is "in the page", stop and ask again.

What your server should check in every notification

A notification arriving is not the end of the job. Your server should check five things before it believes one:

1. The signature. Your server recalculates it with the webhook secret and compares. If they don't match, the message didn't come from the gateway, so reject it and change nothing.
2. The amount and currency. They should match the order in your own database; a successful payment for a different amount isn't enough. Otherwise a real R10 payment could unlock a R1,000 order.
3. The order itself. The notification should name an order your server created, and that order shouldn't already be paid. Gateways can send the same notification more than once, so the second copy should change nothing.
4. What the status actually means. Not every status that isn't "paid" means "failed". Some mean pending or under review. Mark an order failed only on a status the gateway's documentation says is final, and let a later notification still change it.
5. How old it is, where the gateway includes a timestamp. A genuine notification that someone captured and sends again later should be rejected.

Then the server should answer the gateway quickly with a success response, and do slower work such as sending the receipt email afterwards. If the gateway doesn't get a timely answer, it may treat the notification as failed and try again.

Every gateway has its own exact recipe for the signature: which fields go in, in what order, how they're encoded and which algorithm hashes them. Your AI will often guess the recipe from a different gateway, and one wrong detail makes every check fail. Our guide to webhook signature verification failures covers the usual causes.

How card payments and Instant EFT differ

South African customers often prefer Instant EFT to a card, so it's worth knowing how the two differ before you pick a gateway.

Your code barely changes between the two. Both use the same hosted checkout and the same notification. The differences are in what the customer sees and in which statuses your server has to handle, which is why check 4 above, what the status actually means, matters.

Test in the sandbox first, then go live

Most gateways give you test keys for a sandbox, a practice copy of the gateway where you can run fake payments. Build and test the whole loop there: pay, receive the notification, check it, mark the order paid. Only then swap the test keys for live ones.

• Keep keys in settings, not in the code. Store them as environment variables or your builder's secrets, so going live means changing values, not rewriting code. If a value works on your computer and vanishes after you publish, our guide to environment variables that stop working after deploy explains why.
• Read the gateway's testing page before your first test. Test modes aren't all the same. Ozow, for example, warns that its staging environment moves real money unless you pay with its Demo Bank, and that a test payment made on a live account settles for real.
• Your notification address must be public. The gateway can't reach a preview only you can open, or an address on your own computer. A notification that never arrives usually has this cause.
• Make one small real payment yourself after going live, before you share the checkout with anyone, and confirm the order was marked paid by the notification, not by the return page.

Where AI coding agents usually get payments wrong

An AI coding agent will produce payment code that runs. Whether it's safe depends on what you asked for. These are the ones beginners run into most:

• It marks the order paid on the return page. It's the simplest code to write, and it's the one that lets people take things without paying.
• It puts a secret key in the browser code, often "just for testing", and it stays there.
• It checks the signature but not the amount or the order. A real, correctly signed payment for the wrong order still gets through.
• It guesses the signature recipe from another gateway, so every check fails, and then it "fixes" the failure by removing the check.
• It rewrites working payment code while changing something else. Once payments work, tell your AI which files it must not change unless you ask.

Choosing a gateway: what to look for

This page doesn't rank gateways or quote their fees. Fees change and depend on how you sell. Look for these instead, then read each gateway's current pricing page:

• It pays out to a South African bank account, in rand, for your kind of business.
• It supports the methods your customers actually use: cards, Instant EFT, or both.
• It has a sandbox with test keys, and a testing page that says whether tests can move real money.
• Its developer documentation describes a signed payment notification, and your AI can read that documentation.
• On the pricing page: the fee per method, any monthly or payout fees, and how long payouts take.

Your customers' names, emails and addresses are personal information, so POPIA applies as soon as you take orders. Our guide to whether your AI builder's backend is POPIA compliant covers what to check.

The prompt to give your AI

Paste this into your AI website builder's chat, or give it to your AI coding agent. Fill in the brackets. If your AI can't browse the web, paste in the gateway's developer documentation for checkout and payment notifications yourself.

I'm not a coder. Add online payments to my app using [gateway name].
What customers buy: [one sentence]. Price comes from: [my database / a fixed price].

Build it this way:
1. A server function creates the payment and sends the customer to
   [gateway name]'s own hosted checkout page. No card form on my site.
2. All secret keys, passphrases and webhook secrets stay on the server,
   stored as secrets or environment variables. None in browser code.
3. The return page only says "we're confirming your payment".
   It must not mark the order paid.
4. A second server function receives [gateway name]'s payment
   notification (webhook) and, before changing anything, checks:
   - the signature, using [gateway name]'s own documented method
   - that the amount and currency match the order in my database
   - that the order exists and isn't already paid
   - what the status means (paid, pending or failed)
   Only if every check passes and the status means paid does it mark
   the order paid. Either way, it replies quickly with success.
5. Use sandbox (test) keys now. Tell me exactly which values I change
   to go live.

Before writing code, give me the links to [gateway name]'s current
documentation you are following for the checkout and for checking the
notification. If you can't find them, say so instead of guessing.
Don't change any other part of my app.

What to check in the AI's answer

• It gave you documentation links from the gateway's own site. Open them. If the AI describes the signature from memory, ask it to follow the documentation instead.
• Search the browser code for the secret. Ask your AI: "Which files run in the browser, and do any of them contain a secret key?" The answer should be no.
• The return page doesn't change the order. Ask: "What happens to the order if someone opens the success page without paying?" The answer should be nothing.
• All four checks from step 4 of the prompt are there. If the amount check or the "already paid" check is missing, ask for it by name.
• A failed signature check rejects the message. It shouldn't be switched off, skipped "in test mode" or logged and ignored.
• It told you which values to change to go live. They should be keys and addresses, not code.

Then run a full sandbox payment and watch your server's logs. You're looking for a line showing that the notification arrived and its signature matched, not just a thank-you page.