Gateway Developer Documentation: If you are looking for Dev Docs related to PayGate, please see here.

This guide provides the fastest path to successfully accepting payments using PayFast APIs.

Step 1 — Create or access your PayFast account

To integrate PayFast, you must have an active merchant account.

You will need:

Merchant ID
Merchant Key
Passphrase (if configured)

These credentials are available in your PayFast dashboard.

Step 2 — Configure your test environment (Sandbox)

Before going live, always test your integration.

Use the PayFast sandbox to simulate transactions without processing real payments.

Sandbox testing allows you to:

Validate requests
Confirm signature generation
Test payment flows
Verify Instant Transaction Notifications (ITN)
Debug safely

See the Sandbox Test Environment page for test credentials and setup instructions.

Step 3 — Choose an integration method

PayFast supports multiple integration options depending on your use case:

Onsite Payments (Recommended)

Accept payments using PayFast’s secure hosted checkout experience while keeping customers within your purchase flow.

With Onsite Payments, sensitive card data is handled securely by PayFast, reducing your PCI compliance burden while providing a seamless checkout experience.

Best for:

Quick integration
Reduced PCI scope
Secure card data handling by PayFast
Minimal development effort

Custom Integration (Direct API)

Integrate payments directly into your application using PayFast’s APIs for complete control over the checkout experience.

This approach allows you to build fully customised payment flows while handling payment requests and responses programmatically on your server.

Best for:

Fully customised checkout experiences
Advanced payment workflows
Server-to-server integrations
Deep integration with existing systems

How the PayFast payment flow works

The typical PayFast payment lifecycle involves the customer, your application, and PayFast’s secure payment platform.

sequenceDiagram
    participant Customer
    participant MerchantSite as Merchant App / Website
    participant PayFast
    participant MerchantServer as Merchant Server (ITN Endpoint)

    Customer->>MerchantSite: Initiates checkout
    MerchantSite->>PayFast: Send payment request (signed)
    PayFast->>Customer: Display secure payment page
    Customer->>PayFast: Enter payment details
    PayFast-->>MerchantSite: Redirect after payment
    PayFast-->>MerchantServer: Send ITN (POST notification)
    MerchantServer->>PayFast: Validate ITN
    MerchantServer-->>MerchantSite: Update order status

Important:
Always use the Instant Transaction Notification (ITN) as the final confirmation of payment status.

Step 4 — Implement authentication and request signing

All PayFast requests must be securely signed.

You must:

Generate a signature using your Merchant Key and passphrase
Include required parameters
Validate responses from PayFast

See Authentication & Signature for implementation details.

Step 5 — Process a test payment

Perform a sandbox transaction to verify your integration:

Initiate a payment request
Complete the payment flow
Confirm redirection back to your site
Verify transaction status

Step 6 — Handle payment confirmation (ITN)

PayFast sends an Instant Transaction Notification (ITN) to confirm the payment result.

Your server must:

Accept POST notifications from PayFast
Validate the signature
Verify the transaction status
Update your system accordingly

📘
Always rely on ITN as the authoritative payment result.

Step 7 — Go live

When testing is complete:

Switch from sandbox to live credentials
Update URLs to production endpoints
Disable test mode
Monitor transactions closely during launch

PayFast API Reference

For detailed request/response specifications, endpoints, parameters, and examples, refer to the hosted PayFast API documentation:

PayFast API Documentation (Postman)

This reference includes:

Endpoint details
Required parameters
Authentication requirements
Example requests and responses
Integration testing guidance

Use this documentation when building custom integrations or troubleshooting specific API behaviour.

If you are implementing a custom server-to-server integration, the API reference above is the primary technical source.

Choose the right integration approach

Onsite Payments (Hosted Checkout)

Best for a fast, secure integration with reduced PCI scope.

Create a Payment Request

Generate a signed request using your Merchant ID, Merchant Key, and (optional) passphrase.

↓

Redirect to PayFast Checkout

Send the customer to PayFast’s secure hosted checkout to complete payment.

↓

Customer Completes Payment

PayFast collects payment details securely and processes the transaction.

↓

Customer Returns to Your Site

The customer is redirected back to your return/cancel URL after checkout.

↓

Receive ITN Confirmation

PayFast sends an Instant Transaction Notification (ITN) to your server. Validate the signature and update the order status in your system.

Overview of the Onsite Payments flow (hosted checkout + ITN confirmation).

Custom Integration (Direct API)

Best for full control and advanced use cases (server-to-server integration).

Authenticate & Sign Requests

Implement authentication and signature generation for all API requests.

↓

Create / Manage Payment Programmatically

Your server calls PayFast APIs to create transactions and control the payment flow.

↓

Present Checkout Experience

Your application controls the checkout UI and user journey (based on your integration design).

↓

Handle API Responses & Status

Interpret responses, handle errors, and manage payment state within your application.

↓

Receive ITN Confirmation

PayFast sends an ITN to confirm the final payment result. Validate it and update your internal order/payment records.

Overview of the Custom Integration flow (Direct API + ITN confirmation).

Onsite Payments delegate sensitive payment handling to PayFast’s hosted checkout, reducing PCI scope and development effort.

Custom Integration (Direct API) gives you full control over the checkout experience but requires server-side integration and additional security considerations.

Not sure which approach to choose? Start with Onsite Payments — you can migrate to a Custom Integration later if needed.

Need help?

Refer to the detailed guides in this documentation for advanced configuration, error handling, and integration patterns.

/