spree_payfast is a Spree Commerce extension that integrates PayFast's Custom Integration (hosted-redirect) flow into your Spree store. It supports Credit/Debit Cards, Instant EFT, and Zapper, allowing South African merchants to accept payments seamlessly and securely.
- Hosted Checkout Redirect: Customers are redirected to PayFast's secure portal to complete payments, ensuring full PCI compliance (no card data touches your server).
- ITN (Instant Transaction Notification) Support: Webhook endpoints handle async status updates from PayFast to automatically mark orders as complete or failed.
- Native Signature Generation: MD5 secure signatures are built directly within the gem, avoiding external PayFast Ruby SDK dependencies.
- Sandbox & Live Modes: Toggle between testing and production environments directly from the Spree admin panel.
- Add this extension to your
Gemfile:
gem 'spree_payfast', github: 'truehostcloud/spree_payfast'- Install the gem using Bundler:
bundle install- Copy and run the required database migrations:
bundle exec rails g spree_payfast:install- Log into your Spree Admin Panel.
- Navigate to Settings → Payments → Payment Methods.
- Click New Payment Method.
- Set the Provider to
Spree::Gateway::Payfast. - Enter a Name (e.g., "PayFast") and Description.
- Click Create to reveal the configuration fields.
- Fill in your PayFast API credentials:
- Merchant ID
- Merchant Key
- Passphrase (Must match the salt passphrase set in your PayFast dashboard)
- Test Mode (Check for Sandbox, uncheck for Live)
Important: PayFast will only be available for orders where the currency is ZAR (South African Rand). The gateway is hidden for all other currencies at runtime.
When a payment succeeds or fails on the PayFast portal, PayFast will send a POST request to your store's ITN endpoint to update the order status.
Ensure your store is publicly accessible online (or use a tool like Ngrok for local development) so PayFast can reach:
https://your-store-domain.com/payfast/itn
You do not need to manually configure this URL in the PayFast dashboard; the gem automatically sends this notify_url to PayFast during the checkout redirect.
The ITN validator resolves PayFast hostnames and checks the webhook caller IP against the resolved addresses.
You can override the host list with the PAYFAST_VALIDATION_HOSTS environment variable (comma-separated):
PAYFAST_VALIDATION_HOSTS=www.payfast.co.za,sandbox.payfast.co.za,w1w.payfast.co.za,w2w.payfast.co.zaDefault hosts (when the env var is not set):
www.payfast.co.zasandbox.payfast.co.zaw1w.payfast.co.zaw2w.payfast.co.za
First bundle your dependencies, then run rake. rake will default to building the dummy app if it does not exist, then it will run specs. The dummy app can be regenerated by using rake test_app.
bundle exec rspec specWhen testing your integration manually using the Sandbox Test Mode, ensure you use the generated test credentials provided in the PayFast Sandbox Dashboard.
This project is licensed under the BSD-3-Clause License.