How to use Rabet

Prerequisites

• An existing Laravel project containing composer.json and artisan.
• Go to build from source, plus PHP and Composer for Laravel work.
• A provider sandbox account and token, with an HTTPS plan for callback and webhook routes.
• Version control and a backup before generation.

Published install path — reviewed foundation prerelease

The exact 0.1.0-foundation.6 version is pinned so installation cannot move when an npm dist-tag changes. It is not a production-readiness claim or a substitute for code review and sandbox testing. In PowerShell, keep the scoped package spec quoted so @ is passed to npm instead of parsed as splatting.

npm install --global "@ween.aro7/rabet-kit@0.1.0-foundation.6"

Verify the public package page on npm. You can instead build from source in the next step.

1. Build from source

Executable path syntax differs across Windows, macOS, and Linux. From the repository root, run:

go build -trimpath -o dist/rabet ./cmd/rabet

2. Configure sandbox

Keep RABET_UPAYMENTS_TOKEN and RABET_WEBHOOK_SECRET in private secret storage and set RABET_UPAYMENTS_ENVIRONMENT=sandbox. These public names are shared by the tool and generated template. Never place the values in the repository, browser, or a support message.

3. Check the environment

Run ./dist/rabet doctor. It checks that the token variable exists, makes a lightweight reachability request to the selected UPayments host, and reports PHP, Composer, and cloudflared detection. It does not prove the gateway accepts the credential.

4. Preview the file plan

Run ./dist/rabet init --dir /path/to/laravel without --apply. Review all eight paths and byte counts: .env.rabet.example, app/Models/RabetPayment.php, app/Payment/PaymentController.php, app/Payment/UPaymentsClient.php, app/Payment/WebhookController.php, config/rabet.php, database/migrations/2026_07_17_000000_create_rabet_payments_table.php, and routes/rabet.php. The preview is a file plan, not a full diff.

5. Apply after review

Run ./dist/rabet init --dir /path/to/laravel --apply and accept the interactive confirmation. Generation stays inside the project root and skips existing files instead of overwriting them. --force bypasses the prompt and is intended only for controlled CI, not the normal path.

6. Complete the Laravel integration

The generator creates PaymentController and an authenticated create-payment endpoint, but checkout remains disabled by default and fails closed. Copy the required values from .env.rabet.example into the private application .env, configure offers, prices, and the token, run the migration, register routes/rabet.php in bootstrap/app.php or an appropriate route provider, and run it inside a Laravel server runtime. Never commit secrets.

The endpoint calculates amount, currency, and order state on the server; it accepts only offer_id and an optional payment method from the browser. Never trust amount or order data from the DOM or JavaScript.

rabet init does not install the Web Component. Download the public component copy that matches the source into an application asset such as public/rabet-button.js, and serve it from the same origin at /rabet-button.js. Use checkout-id as an opaque value unique to the authenticated user and payment attempt; never put an email address or phone number in it. If the component requires review, clear the block only after server-to-server verification, then call clearPreviousAttemptReview({ verified: true }) when a new attempt is safe. After configuring the generated endpoint, connect the component as follows:

<script type="module" src="/rabet-button.js"></script>
<rabet-button
  endpoint="/rabet/create-payment"
  offer-id="foundation"
  checkout-id="opaque-user-checkout-attempt"
  payment-method="knet">
</rabet-button>

7. Test and verify

Exercise the complete sandbox flow and associate the local order with the provider identifier. On 17 July 2026, a credentialed 1.500 KWD UPayments Sandbox payment reached CAPTURED and an independent server-side status request confirmed it. The credential was not stored and no value seen previously may be reused. This is not production evidence: the public /return route returned 404 at capture time, and this release adds a safe status-page fallback, but no public backend or webhook is deployed yet.

The optional ./dist/rabet webhook listen --port 8787 --path /rabet/webhook listener binds to 127.0.0.1 and does not create a public tunnel automatically. The generated webhook path independently fetches gateway status and accepts success only for CAPTURED.

8. Optionally use MCP

An MCP client launches the version-pinned npx --package="@ween.aro7/rabet-kit@0.1.0-foundation.6" -- rabet-mcp command as a stdio server; it is not an interactive shell. A client configuration looks like this:

{
  "mcpServers": {
    "rabet": {
      "command": "npx",
      "args": ["--yes", "--package=@ween.aro7/rabet-kit@0.1.0-foundation.6", "--", "rabet-mcp"],
      "env": {
        "RABET_UPAYMENTS_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Load the token from the process secret store before starting the MCP client; do not write it into the configuration file. The public surface is limited to list_payment_methods, create_payment_link, and get_payment_status; there are no public refund, capture, or payout tools.

create_payment_link requires a positive amount, order_id, description, return_url, cancel_url, and notification_url. In production, use merchant-owned HTTPS URLs for success return, cancellation return, and webhook notification. Currency is optional and defaults to KWD; customer fields are optional.

To select KNET explicitly, send payment_method:"knet". The adapter maps it to UPayments paymentGateway.src, but the provider must first enable White Label and KNET on the merchant account. Leaving the field empty preserves the normal UPayments method-selection page.

1. For the first call, send the required arguments without the flag or with confirm:false. The server returns pending_confirmation and creates nothing.
2. The integrating client must display the details and obtain human approval, then repeat the same arguments with the explicit confirm:true flag. The flag is only a boolean and is not technical proof of human presence; approval is the integrating client's responsibility.

Production checklist

• Obtain production credentials directly from the provider after its approval; Rabet does not activate the merchant account.
• Use private secret storage for the unified names RABET_UPAYMENTS_TOKEN, RABET_UPAYMENTS_ENVIRONMENT=production, and RABET_WEBHOOK_SECRET.
• Use HTTPS callbacks and webhooks, rotate secrets, and review authorization, logging, and incident response.
• Validate amount, currency, and order state on the server; complete sandbox testing and then a small, monitored production test after direct owner approval.
• Configure cancellations, refunds, and disputes in the merchant/provider process, and obtain legal and security review appropriate to the business.