payfast_flutter 0.0.7

Flutter SDK for PayFast payment gateway integration with Android, iOS, and Web support.

PayFast Flutter SDK

Simple PayFast payments for Android, iOS, and Flutter Web using the published package name payfast_flutter.

Installation

dependencies:
  payfast_flutter: ^0.0.6

import 'package:payfast_flutter/payfast_flutter.dart';

Quick start

Use the shortest API:

await PayFast.pay(
  context: context,
  merchantId: const String.fromEnvironment('PAYFAST_MERCHANT_ID'),
  securedKey: const String.fromEnvironment('PAYFAST_SECURED_KEY'),
  basketId: 'ORDER-${DateTime.now().millisecondsSinceEpoch}',
  amount: '1000.00',
  callbackBaseUrl: 'https://your-domain.com',
  webTokenUrl: 'http://127.0.0.1:8080/api/payfast/access-token',
  onResult: (result) {
    debugPrint(result.toString());
  },
);

What PayFast.pay(...) handles for you

• creates a PayFastConfig.simple(...) internally
• derives success, failure, and checkout URLs from one callback base URL
• uses the current browser origin automatically on Flutter Web
• fetches the web access token from webTokenUrl when needed
• still lets advanced users drop down to PayFastConfig and PayFast.startPayment(...)

What the app using this package must provide

Shared inputs

• merchantId
• securedKey
• basketId
• amount
• onResult

Android / iOS

Also provide:

• callbackBaseUrl

Optional:

• currency
• txnDesc
• customerEmail
• customerMobile
• environment
• additionalDescription

Flutter Web

Provide one token source:

• webTokenUrl, or
• webAccessToken, or
• accessTokenProvider

Important web rules:

• generate the access token on your backend in production
• do not expose your production securedKey in the browser
• successUrl and failureUrl must use the same origin as the web app
• start checkout from a user click so the browser does not block the popup

Android / iOS example

await PayFast.pay(
  context: context,
  merchantId: 'YOUR_MERCHANT_ID',
  securedKey: 'YOUR_SECURED_KEY',
  basketId: 'ORDER-123',
  amount: '1000.00',
  callbackBaseUrl: 'https://your-domain.com',
  onResult: (result) {
    debugPrint(result.message);
  },
);

Flutter Web example

await PayFast.pay(
  context: context,
  merchantId: 'YOUR_MERCHANT_ID',
  securedKey: 'YOUR_SECURED_KEY',
  basketId: 'ORDER-123',
  amount: '1000.00',
  webTokenUrl: 'http://127.0.0.1:8080/api/payfast/access-token',
  onResult: (result) {
    debugPrint(result.message);
  },
);

Local web token proxy

The repo includes a local development proxy in example/tool/payfast_token_server.dart.

Default access-token URL:

http://127.0.0.1:8080/api/payfast/access-token

Health check URL:

http://127.0.0.1:8080/api/payfast/health

Start the local proxy

From the example/ folder:

cd /d C:\payfast_flutter\example
dart run tool\payfast_token_server.dart

Run Flutter Web with defines

cd /d C:\payfast_flutter\example
flutter run -d chrome ^
  --dart-define=PAYFAST_MERCHANT_ID=YOUR_MERCHANT_ID ^
  --dart-define=PAYFAST_SECURED_KEY=YOUR_SECURED_KEY ^
  --dart-define=PAYFAST_WEB_TOKEN_PROXY_URL=http://127.0.0.1:8080/api/payfast/access-token

If port 8080 is busy

A Windows socket error 10048 means port 8080 is already occupied.

cd /d C:\payfast_flutter\example
set PAYFAST_TOKEN_PROXY_PORT=8081 && dart run tool\payfast_token_server.dart

Then run the web app with the matching URL:

cd /d C:\payfast_flutter\example
flutter run -d chrome ^
  --dart-define=PAYFAST_MERCHANT_ID=YOUR_MERCHANT_ID ^
  --dart-define=PAYFAST_SECURED_KEY=YOUR_SECURED_KEY ^
  --dart-define=PAYFAST_WEB_TOKEN_PROXY_URL=http://127.0.0.1:8081/api/payfast/access-token

Token proxy contract

When using webTokenUrl, the package sends JSON like this:

{
  "merchantId": "YOUR_MERCHANT_ID",
  "securedKey": "YOUR_SECURED_KEY",
  "basketId": "ORDER-123",
  "amount": "1000.00",
  "currencyCode": "PKR"
}

Your backend/proxy should return JSON containing either:

{
  "accessToken": "YOUR_TOKEN"
}

or:

{
  "ACCESS_TOKEN": "YOUR_TOKEN"
}

Troubleshooting

Could not reach token proxy / Failed to fetch

This means the browser could not reach the URL in PAYFAST_WEB_TOKEN_PROXY_URL.

Check these items:

• confirm the proxy/backend is running
• confirm the host, port, and path match exactly
• confirm the health URL opens in the browser
• if you changed --dart-define, do a full restart instead of hot reload

Merchant SECRET KEY is not matched

This means the proxy is reachable, but the merchant credentials do not match.

Check:

• PAYFAST_MERCHANT_ID
• PAYFAST_SECURED_KEY
• sandbox vs live credential mix-ups
• accidental spaces in values

Example app defines

The example reads these compile-time values:

• PAYFAST_MERCHANT_ID
• PAYFAST_SECURED_KEY
• PAYFAST_CALLBACK_BASE_URL
• PAYFAST_WEB_TOKEN_PROXY_URL

Testing

Run package tests:

cd /d C:\payfast_flutter
flutter test

Run package analysis:

cd /d C:\payfast_flutter
flutter analyze

Support

• GitHub Repo: https://github.com/abdullah4445/payfast_flutter
• GitHub Issues: https://github.com/abdullah4445/payfast_flutter/issues
• WhatsApp: https://wa.me/923271774145
• JazzCash: 03271774145