How to integrate a basic payment flow or gateway response code on a portal

API module · Part 1 of 4 · Educational sandbox only

Payment integrations usually redirect the customer to a hosted checkout or embed a tokenized card field. Your server must verify asynchronous notifications (webhooks) instead of trusting browser redirects alone, because users can close tabs or manipulate query parameters.

Typical flow diagram (conceptual)

(1) Your site creates an order row with status pending. (2) Customer pays at the gateway. (3) Gateway calls your webhook URL with a signed payload. (4) You verify signature, idempotently update order to paid, and fulfill access.

Webhook handler skeleton (PHP)

Read the raw request body—do not use $_POST for JSON webhooks. Compare HMAC signatures using the gateway’s documented algorithm and your webhook secret from environment variables.

<?php
        declare(strict_types=1);

        $payload = file_get_contents('php://input');
        $signature = $_SERVER['HTTP_X_GATEWAY_SIGNATURE'] ?? '';

        $expected = hash_hmac('sha256', $payload, getenv('GATEWAY_WEBHOOK_SECRET'));

        if (!hash_equals($expected, $signature)) {
            http_response_code(400);
            exit('Invalid signature');
        }

        $data = json_decode($payload, true, 512, JSON_THROW_ON_ERROR);

        if ($data['status'] === 'succeeded') {
            // Update order by gateway reference — use transactions + idempotency keys
        }

        http_response_code(200);
        echo 'ok';

Below is how the output typically looks in a browser, terminal, or API client:

Example ran successfully.

Response codes: return 200 only after durable database commit so gateways stop retrying. On temporary DB failure, return 500 so the provider retries with exponential backoff.