POST

{{ __('Initiate Payment') }}

{{ __('Create a hosted checkout session for a merchant-supported currency. The returned payment_url should be opened by the customer.') }}

{{ request()->getSchemeAndHttpHost() }}/api/v1/initiate-payment
{{ __('API key required') }} {{ __('HMAC signature required') }} {{ __('Sandbox + production') }} {{ __('Currency wallet checked') }}
{{ __('Gateway Selection') }} {{ __('Hosted checkout first applies merchant currency and wallet rules, then the gateways selected on Merchant API Config. allow_payment_methods is only an optional extra filter.') }}

{{ __('Request Headers') }}

{{ __('Header') }} {{ __('Value') }} {{ __('Required') }} {{ __('Description') }}
Content-Type application/json {{ __('Yes') }} {{ __('Request content type') }}
Accept application/json {{ __('Yes') }} {{ __('Expected response type') }}
X-Environment sandbox | production {{ __('Yes') }} {{ __('Use sandbox for testing and production for live payments') }}
X-Merchant-Key {merchant_key} {{ __('Yes') }} {{ __('Merchant identifier from the API Config page') }}
X-API-Key {api_key} {{ __('Yes') }} {{ __('API key for the selected environment') }}
X-Timestamp {unix_timestamp} {{ __('Yes') }} {{ __('Current Unix timestamp in seconds. Requests outside the allowed tolerance are rejected.') }}
X-Signature sha256={hmac} {{ __('Yes') }} {{ __('HMAC-SHA256 of timestamp.METHOD.path_with_query.raw_body using the API Secret for the selected environment.') }}

{{ __('Request Parameters') }}

{{ __('Parameter') }} {{ __('Type') }} {{ __('Required') }} {{ __('Description') }}
payment_amount number {{ __('Yes') }} {{ __('Payment amount. Minimum value is 1.00.') }}
currency_code string {{ __('Yes') }} {{ __('3-letter currency code. Must be enabled for the merchant and backed by an active merchant wallet.') }}
ref_trx string {{ __('Yes') }} {{ __('Your unique order or transaction reference. Max 60 characters.') }}
success_redirect url {{ __('Yes') }} {{ __('Customer is redirected here after a successful hosted checkout.') }}
cancel_redirect url {{ __('Yes') }} {{ __('Customer is redirected here when checkout is canceled or cannot continue.') }}
ipn_url url {{ __('Yes') }} {{ __('Server-to-server webhook URL for payment status updates.') }}
description string {{ __('No') }} {{ __('Payment description visible in merchant transaction context.') }}
customer_name string {{ __('No') }} {{ __('Customer name. Max 100 characters.') }}
customer_email email {{ __('No') }} {{ __('Customer email address. Max 100 characters.') }}
allow_payment_methods string | array {{ __('No') }} {{ __('Optional keyword filter applied after merchant gateway rules. Example: "stripe,paypal" or ["stripe","paypal"].') }}

{{ __('Gateway Availability Response Fields') }}

{{ __('Field') }} {{ __('Type') }} {{ __('Meaning') }}
info.merchant_payment_methods_restricted boolean {{ __('true when the merchant has selected specific gateways in API Config.') }}
info.merchant_payment_method_ids array {{ __('Eligible deposit method IDs for the requested currency.') }}
info.merchant_payment_method_codes array {{ __('Eligible method codes that can appear on hosted checkout.') }}

{{ __('Code Examples') }}

curl -X POST "{{ request()->getSchemeAndHttpHost() }}/api/v1/initiate-payment" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Environment: sandbox" \
  -H "X-Merchant-Key: test_merchant_key" \
  -H "X-API-Key: test_api_key" \
  -H "X-Timestamp: 1778650000" \
  -H "X-Signature: sha256=generated_hmac_signature" \
  -d '{
    "payment_amount": 250.00,
    "currency_code": "USD",
    "ref_trx": "ORDER_12345",
    "description": "Premium Subscription",
    "success_redirect": "https://merchant.example/payments/success",
    "cancel_redirect": "https://merchant.example/payments/cancel",
    "ipn_url": "https://merchant.example/webhooks/{{ strtolower(setting('site_title')) }}",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "allow_payment_methods": ["stripe", "paypal"]
  }'
<?php

use Illuminate\Support\Facades\Http;

$payload = [
    'payment_amount' => 250.00,
    'currency_code' => 'USD',
    'ref_trx' => 'ORDER_12345',
    'description' => 'Premium Subscription',
    'success_redirect' => route('payments.success'),
    'cancel_redirect' => route('payments.cancel'),
    'ipn_url' => route('webhooks.{{ strtolower(setting('site_title')) }}'),
    'customer_name' => 'John Doe',
    'customer_email' => 'john@example.com',
    'allow_payment_methods' => ['stripe', 'paypal'],
];

$body = json_encode($payload, JSON_THROW_ON_ERROR);
$timestamp = (string) time();
$path = '/api/v1/initiate-payment';
$signature = hash_hmac(
    'sha256',
    $timestamp.'.POST.'.$path.'.'.$body,
    config('services.{{ strtolower(setting('site_title')) }}.api_secret')
);

$response = Http::withHeaders([
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'X-Environment' => 'sandbox',
    'X-Merchant-Key' => config('services.{{ strtolower(setting('site_title')) }}.merchant_key'),
    'X-API-Key' => config('services.{{ strtolower(setting('site_title')) }}.api_key'),
    'X-Timestamp' => $timestamp,
    'X-Signature' => 'sha256='.$signature,
])->withBody($body, 'application/json')
    ->post('{{ request()->getSchemeAndHttpHost() }}/api/v1/initiate-payment')
    ->throw()
    ->json();

return redirect()->away($response['payment_url']);
const crypto = require('crypto');

const payload = {
  payment_amount: 250.00,
  currency_code: 'USD',
  ref_trx: 'ORDER_12345',
  description: 'Premium Subscription',
  success_redirect: 'https://merchant.example/payments/success',
  cancel_redirect: 'https://merchant.example/payments/cancel',
  ipn_url: 'https://merchant.example/webhooks/{{ strtolower(setting('site_title')) }}',
  customer_name: 'John Doe',
  customer_email: 'john@example.com',
  allow_payment_methods: ['stripe', 'paypal']
};

const body = JSON.stringify(payload);
const timestamp = Math.floor(Date.now() / 1000).toString();
const path = '/api/v1/initiate-payment';
const signature = crypto
  .createHmac('sha256', process.env.ZilitPay_API_SECRET)
  .update(`${timestamp}.POST.${path}.${body}`)
  .digest('hex');

const response = await fetch('{{ request()->getSchemeAndHttpHost() }}/api/v1/initiate-payment', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'X-Environment': 'sandbox',
    'X-Merchant-Key': process.env.ZilitPay_MERCHANT_KEY,
    'X-API-Key': process.env.ZilitPay_API_KEY,
    'X-Timestamp': timestamp,
    'X-Signature': `sha256=${signature}`
  },
  body
});

const data = await response.json();

if (!response.ok) {
  throw new Error(data.error || 'Payment initiation failed');
}

window.location.href = data.payment_url;

{{ __('Success Response') }}

200 OK {{ __('Payment session created') }}
{
  "payment_url": "https://{{ setting('site_title') }}.test/payment/checkout?token=encrypted&signature=signed",
  "info": {
    "ref_trx": "ORDER_12345",
    "description": "Premium Subscription",
    "ipn_url": "https://merchant.example/webhooks/{{ strtolower(setting('site_title')) }}",
    "cancel_redirect": "https://merchant.example/payments/cancel",
    "success_redirect": "https://merchant.example/payments/success",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "merchant_id": 1,
    "merchant_name": "Demo Store",
    "amount": 250,
    "currency_code": "USD",
    "environment": "sandbox",
    "is_sandbox": true,
    "allow_payment_methods": ["stripe", "paypal"],
    "merchant_payment_methods_restricted": true,
    "merchant_payment_method_ids": [7],
    "merchant_payment_method_codes": ["stripe-usd"]
  }
}

{{ __('Common Error Responses') }}

422 {{ __('Currency is not enabled for this merchant.') }}

{{ __('The requested currency_code is not in the merchant-supported currency list.') }}

422 {{ __('Receiver wallet for this currency is not available.') }}

{{ __('The merchant owner does not have an active wallet for the requested currency.') }}

401 {{ __('Invalid API credentials.') }}

{{ __('Check X-Environment, X-Merchant-Key, and X-API-Key for the same environment.') }}

GET

{{ __('Verify Payment') }}

{{ __('Fetch the latest status for a hosted checkout transaction. Always verify server-side before fulfilling an order.') }}

{{ request()->getSchemeAndHttpHost() }}/api/v1/verify-payment/{trxId}
{{ __('Use after redirect or IPN') }} {{ __('Merchant scoped') }}

{{ __('Request Headers') }}

{{ __('Header') }} {{ __('Value') }} {{ __('Required') }} {{ __('Description') }}
Accept application/json {{ __('Yes') }} {{ __('Expected response type') }}
X-Environment sandbox | production {{ __('Yes') }} {{ __('Must match the environment used to initiate the payment') }}
X-Merchant-Key {merchant_key} {{ __('Yes') }} {{ __('Merchant identifier from API Config') }}
X-API-Key {api_key} {{ __('Yes') }} {{ __('API key for the selected environment') }}
X-Timestamp {unix_timestamp} {{ __('Yes') }} {{ __('Use the same timestamp format as payment initiation.') }}
X-Signature sha256={hmac} {{ __('Yes') }} {{ __('Sign timestamp.GET./api/v1/verify-payment/{trxId}. using the matching API Secret. The raw body is empty for GET requests.') }}

{{ __('Path Parameter') }}

{{ __('Parameter') }} {{ __('Type') }} {{ __('Required') }} {{ __('Description') }}
trxId string {{ __('Yes') }} {{ __(setting('site_title').' transaction ID returned by hosted checkout or IPN.') }}

{{ __('cURL Example') }}

curl -X GET "{{ request()->getSchemeAndHttpHost() }}/api/v1/verify-payment/TXNQ5V8K2L9N3XM1" \
  -H "Accept: application/json" \
  -H "X-Environment: sandbox" \
  -H "X-Merchant-Key: test_merchant_key" \
  -H "X-API-Key: test_api_key" \
  -H "X-Timestamp: 1778650000" \
  -H "X-Signature: sha256=generated_hmac_signature"

{{ __('Success Response') }}

200 OK {{ __('Completed payment') }}
{
  "status": "success",
  "trx_id": "TXNQ5V8K2L9N3XM1",
  "amount": 237.5,
  "fee": 12.5,
  "currency": "USD",
  "net_amount": 237.5,
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "description": "Premium Subscription",
  "created_at": "2026-05-13T10:30:00.000000Z",
  "updated_at": "2026-05-13T10:35:45.000000Z"
}

{{ __('Payment Status Values') }}

{{ __('Status') }} {{ __('Description') }} {{ __('Recommended Action') }}
pending {{ __('Payment is still processing.') }} {{ __('Wait for IPN or verify again later.') }}
success {{ __('Payment completed successfully.') }} {{ __('Fulfill the order after idempotency checks.') }}
failed {{ __('Payment failed or was canceled.') }} {{ __('Do not fulfill; show retry or cancel state.') }}
{{ __('Idempotency') }} {{ __('Use your ref_trx and the returned trx_id to make fulfillment idempotent. A webhook and a verify request may arrive close together.') }}
GET

{{ __('Site Info') }}

{{ __('Fetch gateway branding, environment labels, and customer-facing checkout metadata for a merchant-authenticated integration.') }}

{{ request()->getSchemeAndHttpHost() }}/api/v1/site-info
{{ __('Merchant auth required') }} {{ __('Checkout branding') }} {{ __('Environment labels') }}

{{ __('cURL Example') }}

curl -X GET "{{ request()->getSchemeAndHttpHost() }}/api/v1/site-info" \
  -H "Accept: application/json" \
  -H "X-Environment: sandbox" \
  -H "X-Merchant-Key: test_merchant_key" \
  -H "X-API-Key: test_api_key" \
  -H "X-Timestamp: 1778650000" \
  -H "X-Signature: sha256=generated_hmac_signature"

{{ __('Success Response') }}

200 OK {{ __('Gateway metadata') }}
{
  "site_name": "{{ setting('site_title') }}",
  "site_logo": "{{ asset(setting('logo')) }}",
  "site_url": "{{ url('/') }}",
  "gateway_name": "{{ setting('site_title') }} Payment Gateway",
  "gateway_description": "Secure payment powered by {{ setting('site_title') }}",
  "features": {
    "ssl_secured": "SSL Secured",
    "instant_processing": "Instant",
    "global_support": "Global",
    "mobile_ready": "Mobile Ready"
  },
  "environments": {
    "production": "Production Mode - Live payment processing is active",
    "sandbox": "Test Mode - This is a test transaction. No real money will be charged"
  },
  "api_version": "1.0",
  "status": "active"
}