GatePay Merchant REST API

Every request is authenticated with a mode-matching client ID and client secret. Keep both credentials on your server and send JSON explicitly.

Required headers

A complete integration starts on your server and ends with webhook verification or a status lookup. The hosted checkout handles the customer-facing payment step.

The REST API is available through an Express merchant application. GatePay creates credentials for the merchant mode, while every request remains scoped to the authenticated application and its owning merchant.

Environment credential matrix

GatePay derives payment methods from the selected currency. Do not send payment_methods in a create-payment request.

Requests containing payment_methods are rejected with HTTP 422. Existing unpaid links use current currency settings.

The response payment_methods array is a creation-time snapshot. Checkout rechecks availability before starting a payment.

Runtime decision order

Configuration matrix

Creates a hosted checkout link for an approved merchant, active fiat currency, and payment methods enabled for merchant payment.

Request body

curl --request POST 'https://gatepay.techvill.net/api/v1/payments' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: ci_test_your_client_id' \
  --header 'X-Client-Secret: cs_test_your_client_secret' \
  --data '{
    "mode": "sandbox",
    "amount": "100.00",
    "currency": "USD",
    "reference": "ORDER-1001",
    "success_url": "https://merchant.example/payments/success",
    "webhook_url": "https://merchant.example/webhooks/payments",
    "cancel_url": "https://merchant.example/payments/cancel",
    "description": "Payment for order 1001",
    "metadata": {"order_id": "1001"}
  }'

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->withHeaders([
        'X-Client-Id' => 'ci_test_your_client_id',
        'X-Client-Secret' => 'cs_test_your_client_secret',
    ])
    ->post('https://gatepay.techvill.net/api/v1/payments', [
        'mode' => 'sandbox',
        'amount' => '100.00',
        'currency' => 'USD',
        'reference' => 'ORDER-1001',
        'success_url' => 'https://merchant.example/payments/success',
        'webhook_url' => 'https://merchant.example/webhooks/payments',
        'cancel_url' => 'https://merchant.example/payments/cancel',
        'description' => 'Payment for order 1001',
        'metadata' => ['order_id' => '1001'],
    ]);

201 Created

{
  "response": {
    "status": {
      "code": 201,
      "message": "Payment link created successfully."
    },
    "records": {
      "code": "payment_link_created",
      "transaction_id": "01KXQBBN9Y1CN3T3NSQHZ15W4V",
      "reference": "ORDER-1001",
      "mode": "sandbox",
      "status": "PENDING",
      "amount": "100.00000000",
      "currency": "USD",
      "payment_methods": ["Stripe", "Paypal"],
      "payment_url": "https://gatepay.techvill.net/pay/8fK2mQ7xN4vR9cT6pL3zWa",
      "expires_at": "2026-07-21T10:30:00+00:00",
      "metadata": {"order_id": "1001"}
    }
  }
}

Idempotency: Repeating the same reference with the identical payload returns the existing link with HTTP 200. Reusing it with changed data returns HTTP 409.

Fetches the current public transaction status using the exact merchant reference supplied during link creation. A found transaction always returns HTTP 200.

Query parameters

curl --get 'https://gatepay.techvill.net/api/v1/payments/status' \
  --data-urlencode 'mode=sandbox' \
  --data-urlencode 'reference=ORDER-1001' \
  --header 'Accept: application/json' \
  --header 'X-Client-Id: ci_test_your_client_id' \
  --header 'X-Client-Secret: cs_test_your_client_secret'

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->withHeaders([
        'X-Client-Id' => 'ci_test_your_client_id',
        'X-Client-Secret' => 'cs_test_your_client_secret',
    ])
    ->get('https://gatepay.techvill.net/api/v1/payments/status', [
        'mode' => 'sandbox',
        'reference' => 'ORDER-1001',
    ]);

200 OK

{
  "response": {
    "status": {
      "code": 200,
      "message": "Transaction status retrieved successfully."
    },
    "records": {
      "code": "transaction_status_retrieved",
      "trx_reference": "01KXQBBN9Y1CN3T3NSQHZ15W4V",
      "reference": "ORDER-1001",
      "status": "SUCCESS",
      "mode": "sandbox",
      "amount": "100.00000000",
      "currency": "USD",
      "payment_method": "Stripe"
    }
  }
}

Redirect the customer to the returned payment_url. Checkout resolves currently available payment methods for the transaction currency and validates the selected method again before processing.

GatePay posts lifecycle events to the webhook_url stored on the payment link. Sandbox and live use the same contract, with delivery records stored in their originating environment.

Supported events

Delivery headers

Successful payment event

{
  "id": "evt_01KX...",
  "event": "payment.status.success",
  "created_at": "2026-07-21T10:00:00+00:00",
  "data": {
    "trx_reference": "01KXQBBN9Y1CN3T3NSQHZ15W4V",
    "reference": "ORDER-1001",
    "status": "SUCCESS",
    "mode": "live",
    "amount": "100.00000000",
    "currency": "USD",
    "payment_method": "Stripe",
    "metadata": {"order_id": "1001"}
  },
  "signature": "hex_hmac_sha256"
}

Laravel signature verification

$timestamp = request()->header('X-Timestamp');
abort_unless(is_string($timestamp) && ctype_digit($timestamp), 401);

$now = time();
abort_if((int) $timestamp < $now - 300 || (int) $timestamp > $now + 300, 401);

$rawBody = request()->getContent();
try {
    $event = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
    abort_unless(is_array($event), 401);

    $receivedSignature = $event['signature'] ?? null;
    abort_unless(is_string($receivedSignature), 401);

    unset($event['signature']);

    $unsignedBody = json_encode(
        $event,
        JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR
    );
} catch (\JsonException) {
    abort(401);
}

$expectedSignature = hash_hmac(
    'sha256',
    $timestamp.'.'.$unsignedBody,
    config('services.merchant_api.client_secret')
);

abort_unless(hash_equals($expectedSignature, $receivedSignature), 401);

return response()->noContent();

Retry policy: Any 2xx response acknowledges delivery. GatePay retries connection failures, timeouts, 408, 429, and 5xx responses immediately, then after 1 minute, 5 minutes, 15 minutes, and 1 hour. Other 4xx responses and redirects are terminal.

Sandbox checkout never calls a real provider or changes a wallet balance. Select an enabled method and use one of the demo values below to produce a deterministic result.

Use this checklist before moving from simulated payments to live checkout. The same REST endpoints work in both environments; the request mode and the complete client credential pair must change together.

Every JSON response uses the existing GatePay response envelope. The HTTP status represents request handling; transaction outcomes returned from status verification still use HTTP 200.

Error response format

{
  "response": {
    "status": {
      "code": 422,
      "message": "The request payload is invalid."
    },
    "records": {
      "code": "validation_error",
      "errors": {
        "currency": ["The selected currency is invalid."]
      }
    }
  }
}