Fast Wallet / Integration guide

Build with Fast Wallet.

Understand your credentials, choose service permissions, and prepare your integration with clear information about the current implementation.

Manage API keys Read the guide

01 / Identity

Separate credentials

New keys are generated in the Fast Wallet database. No original customer keys are included in the clean installation.

02 / Access

Scoped integrations

Select only the services your server requires. Keep credentials out of browsers, public repositories and screenshots.

03 / Delivery

Verify each step

Authentication, provider acceptance and confirmed financial completion are separate steps.

Getting started

Create your account and sign in.
Open Profile and complete email activation. If needed, choose Resend Activation Email and check your inbox and spam folder.
Complete the identity checks required by your account and payment channel.
Open API Keys, choose a descriptive label and select the required service permissions.
Store the new key in your server's secret configuration. Confirm the intended endpoint is installed and validated before integrating it.

Application address

Website:       https://fast-wallet.com
API namespace: https://fast-wallet.com/v3/

The API namespace is a route prefix, not a single endpoint. Fast Wallet uses the existing PHP application and provider integrations; a new domain does not establish an independent M-Pesa connection.

Manage API keys

The supplied API Keys page creates random credentials, shows the complete new key after creation, and masks it in subsequent listings. Copy it immediately and store it securely.

Expiry: keys created through this page expire after 90 days.
Page limit: up to 20 active, unexpired keys per account.
Services: at least one configured service must be selected.
Revocation: confirm that dependent integrations should stop, then choose Revoke key. Revocation cannot be undone through this page.
Rotation: create a replacement, update your server, validate it in an approved test environment, then revoke the old key.

These are rules of the new key-management page, not a claim that all legacy endpoints enforce identical expiry or scope checks. Endpoint authorization still requires review.

Authentication

Endpoints using the shared API access-control helper accept an API key in the Authorization header. Keep it out of URLs, where it can enter browser history and access logs.

Authorization: Bearer YOUR_FAST_WALLET_API_KEY
Content-Type: application/json

This is a header example only; it sends no request. Replace the placeholder in your server configuration, never in frontend code. The shared helper also recognizes application JWTs; external integrations should not assume a public JWT issuance endpoint.

What access checks mean

The shared helper checks key validity, expiration, account status, email-activation requirements and service permissions. Some legacy routes use their own authentication logic, so this behavior is not uniform across the application. A service selection is not a substitute for provider onboarding or account verification.

Services and implementation status

The catalog contains permission labels recovered from the source migrations. The table distinguishes files present in the supplied code from dependencies still missing. None of these entries is a live-service health check.

Service / scope	Source route	Current limitation
Account & Transactions `account_api`	`/v3/account/` GET account info; POST account creation	Legacy review required Handler present; independent authentication and verbose logging need review before external use. Catalog name does not promise a transaction-history endpoint.
STK Push `stk_push`	`/v3/stk-initiate/`	Missing dependencies MpesaSTK.php and StkCallbackSpool.php missing from this route.
B2C Payments `b2c_payments`	`/v3/pay-request/`	Missing handler Payment-request directory and MpesaB2C.php were not supplied.
B2Pochi Payments `b2pochi_payments`	`/v3/pochi/`	Not verified Handler present; provider configuration and financial-flow testing required.
B2B Payments `b2b_payments`	`/v3/b2b-request-new/`	Missing route Referenced by a migration; directory absent from supplied release.
Transaction Reversals `reversals`	`/v3/reversals/`	Not verified Handler present; provider permissions and reversal reconciliation need testing.
C2B Collections `c2b_collections`	`/v3/gateway/` source directory	Not verified Gateway components present; specific routes, callback registration and provider authentication require validation.
Other catalog entries	`swiftpay`, `lipa_links`, `fundraisers`, `pos_api`, `webhooks`	Permission labels alone do not define an API contract. Do not infer request URLs from them. The webhook manager dependency is missing.

No unverified payment payloads or sample successful transactions are presented as a working API contract. Request schemas and response examples should be published after their handlers have been restored and tested.

Callbacks and transaction status

A request being accepted does not mean funds have moved. Use verified server-side confirmation and reconciliation before marking a payment complete. Preserve pending, failed, reversed and completed outcomes separately.

Use HTTPS callback URLs controlled by your installation.
Verify callbacks according to the actual provider contract; do not trust a browser redirect as proof of payment.
Handle duplicate and out-of-order notifications without repeating credits or payouts.
Do not automatically retry an uncertain payout until its status has been reconciled.
Keep a traceable reference and audit history without logging credentials or verification tokens.

Troubleshooting

Shared-helper error code	Next step
`MISSING_API_KEY`	Send the Authorization header from your server.
`INVALID_API_KEY`	Check the key and its active/revoked state.
`API_KEY_EXPIRED`	Create a replacement key and rotate your integration.
`USER_INACTIVE`	Ask support to review your account status.
`ACCOUNT_NOT_VERIFIED`	Complete email activation in Profile.
`SERVICE_NOT_PERMITTED`	Create an appropriately scoped replacement key; the current page does not edit existing scopes.
`RATE_LIMIT_EXCEEDED`	Reduce request frequency and inspect your subscription limits. Do not repeatedly retry payments.

Error envelopes and HTTP status codes vary between legacy handlers. Inspect the documented contract for the specific endpoint once validated.

No services appear on the API Keys page

An administrator needs to install the service catalog in the Fast Wallet database. Do not reimport the full schema over existing records. Deliberately inactive services should stay inactive until approved.

Activation email could not be sent

The website needs working SMTP credentials, sender configuration and email DNS records. Creating a mailbox alone does not configure the PHP application. Ask the operator to verify SMTP configuration; do not share passwords or activation links with support.

A route returns “page not found”

Check that the route exists in the uploaded source and is deployed at the documented path. A catalog entry does not create its PHP handler.

Before going live

Restore missing endpoint dependencies and review authorization on each route.
Configure your own provider credentials, signing secrets, callback URLs and merchant accounts.
Test activation, scoped keys, expired and revoked keys, and disabled-user access.
Use mocks or an approved sandbox to test failures, repeated requests, duplicate callbacks, reversals and concurrent withdrawals.
Verify balances, fees, ledger postings and audit records against expected results.
Remove temporary setup and diagnostic files from hosting.

For help, contact support@fast-wallet.com. Include the route, time and a redacted error message. Never include passwords, complete API keys, activation links or customer financial records.