{"id":33973790,"url":"https://github.com/tpg/payfast","last_synced_at":"2025-12-13T01:29:42.156Z","repository":{"id":57068430,"uuid":"329911315","full_name":"tpg/payfast","owner":"tpg","description":"A simple PayFast library","archived":false,"fork":false,"pushed_at":"2025-07-16T09:48:29.000Z","size":112,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-09-21T23:19:04.368Z","etag":null,"topics":["payfast","payment","php","subscription","transaction"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tpg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-01-15T12:52:41.000Z","updated_at":"2025-07-16T09:48:32.000Z","dependencies_parsed_at":"2022-08-24T14:23:43.228Z","dependency_job_id":"f3e18d9f-a4b1-4363-a3e5-bf77739cfe9e","html_url":"https://github.com/tpg/payfast","commit_stats":{"total_commits":41,"total_committers":2,"mean_commits":20.5,"dds":0.07317073170731703,"last_synced_commit":"f03297727edd9d631baf99f57933685556bb6f38"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/tpg/payfast","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpg%2Fpayfast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpg%2Fpayfast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpg%2Fpayfast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpg%2Fpayfast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tpg","download_url":"https://codeload.github.com/tpg/payfast/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpg%2Fpayfast/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27697743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-12T02:00:06.775Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["payfast","payment","php","subscription","transaction"],"created_at":"2025-12-13T01:29:41.371Z","updated_at":"2025-12-13T01:29:42.136Z","avatar_url":"https://github.com/tpg.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Run Tests](https://github.com/tpg/payfast/actions/workflows/php.yml/badge.svg)](https://github.com/tpg/payfast/actions/workflows/php.yml)\n\n# Payfast\n\nA simple PayFast library.\n\n# Installation\n\nInstall the PayFast library through composer using the command line:\n\n```bash\ncomposer require thepublicgood/payfast\n```\n\n# Usage\n\nPayFast doesn't currently have an on-site payment solution in production. There is a beta service available, but this library does not support that. When the service is in production and support has been added to the sandbox environment, then I'll update this library. Until then, this library only supports the PayFast custom integration option.\n\n## Merchant\n\nAll transactions require a merchant object. PayFast will provide you with your merchant ID and merchant Key. You will also need to log into your PayFast account and set a passphrase. Although not required by PayFast, this library requires a passphrase to be set.\n\nCreate a new merchant object from the `Merchant` class and pass your authentication data in. You can set the return URL, cancel URL and notify URL on the Merchant instance. You'll want to set all of these to endpoints at your website.\n\n```php\n$merchant = new \\TPG\\PayFast\\Merchant('MERCHANT_ID', 'MERCHANT_KEY', 'PASSPHRASE');\n\n$merchant\n    -\u003esetReturnUrl($returnUrl)\n    -\u003esetCancelUrl($cancelUrl)\n    -\u003esetNotifyUrl($notifyUrl);\n```\n\nSince PayFast will need to have access to these URLs, during testing it can be useful to have access to your test environment. Take a look at [Expose](https://beyondco.de/docs/expose/introduction) if you need this.\n\n## Customer\n\nA customer is not required for any transaction. However, if you'd like to set this data, you can do so by creating a new `Customer` instance and setting the name, email and cell number. This can help improve the customer experience if the user has registered an account with PayFast.\n\n```php\n$customer = new \\TPG\\PayFast\\Customer();\n\n$customer\n    -\u003esetName('First', 'Last')\n    -\u003esetEmail('email@test.com')\n    -\u003esetCellNumber('1234567890');\n```\n\n## Transactions\n\nTransactions are where all the magic happens. The `Transaction` class constructor accepts three parameters: the `Merchant` instance, the value of the transaction (in South African cents) and the name of the item. The name could be some reference to the transaction so users can see what they're paying for on the PayFast website.\n\n```php\n$transaction = new \\TPG\\PayFast\\Transaction($merchant, 10000, 'Item Name');\n```\n\nOnce you have a transaction object, you can make a number of changes:\n\n```php\n$transaction\n    -\u003esetCustomer($customer)                  // Set a customer\n    -\u003esetMerchantPaymentId('PAYID123').       // A payment reference\n    -\u003esetDescription('Item Description')      // A payment description\n    -\u003esetCustomIntegers([                     // Up to 5 custom integers\n        1,\n        2,\n        3,\n        4,\n        5,\n    ])\n    -\u003esetCustomStrings([                     // Up to 5 custom strings\n        'S1',\n        'S2',\n        'S3',\n        'S4',\n        'S5'\n    ])\n    -\u003esetEmailConfirmation(true)            // Where to send email confirmations\n    -\u003esetEmailConfirmationAddress('email@test.com')  // The confirmation email\n    -\u003esetPaymentMethod(\\TPG\\PayFast\\PaymentMethod::ALL); // Payment method\n```\n\nThe payment method is just a way to limit what payment methods you accept. In most cases you'll probably want `PaymentMethod::ALL`, but there are a few others:\n\n```php\nPaymentMethod::ALL;  // All payment methods allowed\nPaymentMethod::CC;   // Credit Cards\nPaymentMethod::DC;   // Debit cards\nPaymentMethod::EFT;  // EFT\nPaymentMethod::MP;   // MasterPass\nPaymentMethod::MC;   // Mobicred\nPaymentMethod::SC;   // SCode\n```\n\nThere is no way to allow a combination of these. It's either all or one.\n\n## Creating a form\n\nCreate a new `PayFast` instance and pass in the transaction. We can now generate a simple HTML form which can be placed in your view. The form ID is always `#payfast_form` so you can refer to it using a bit of JavaScript, or you can pass an integer value to the `form()` method to automatically submit the form after that number of seconds have elapsed.\n\n```php\n$payfast = new \\TPG\\PayFast\\PayFast($transaction);\n\n$submissionDelay = 10; // seconds to wait before automatically submitting the form.\n$form = $payfast-\u003eform($submissionDelay);\n\necho $form;\n```\n\nIf you don't supply a delay, you will need to submit the form yourself. Remember that you should not display this form to the end user and all the form fields are of type \"hidden\".\n\n## Validating the ITN\n\nOnce a transaction has ben submitted to PayFast and you've set a notify URL, you can validate the ITN that comes back from PayFast using the `ItnValidator` class. PayFast recommend setting a header right away and then continuing with the validation process.\n\n```php\nnamespace App\\Http\\Controllers;\n\nclass PayFastController\n{\n    public function webhook(Request $request)\n    {\n        // Create a new validator\n        $validator = new \\TPG\\PayFast\\ItnValidator($request-\u003einput());\n        \n        // From the PayFast docs... Send a 200 response right away...\n        $validator-\u003eflush();\n    \n        // You have access to all the response data through the `PayfastResponse` class.\n        $response = $validator-\u003eresponse();\n        \n        $mpid = $response-\u003emerchantPaymentId();  // Original payment ID set on the transaction\n        $pfid = $response-\u003epayFastPaymentId();   // PayFast's payment ID\n        $name = $response-\u003ename();           // Item name or order number\n        $description = $response-\u003edescription();    // Item or order description\n        $gross = $response-\u003eamountGross();        // Total charge\n        $fee = $response-\u003eamountFee();          // Payfast fee amount\n        $net = $response-\u003eamountNet();          // Net amount\n        $integer = $response-\u003ecustomIntegers();    // Array of custom integers\n        $string = $response-\u003ecustomStrings();     // Array of custom strings\n        \n        $firstName = $response-\u003ecustomer()-\u003efirstName();      // Customers first name\n        $lastName = $response-\u003ecustomer()-\u003elastName();       // Customers last name\n        $emailAddress = $response-\u003ecustomer()-\u003eemailAddress();   // Customers email address\n        $cellNumber = $response-\u003ecustomer()-\u003ecellNumber();     // Customers cell number\n        \n        $signature = $response-\u003esignature();                  // Signature for validation\n        \n        //--------------------\n        \n        // To validate the transaction, first ensure the transaction is COMPLETE:\n        if ($response-\u003epaymentStatus() !== \\TPG\\PayFast\\PaymentStatus::COMPLETE) {\n            // incomplete...\n        }\n        \n        // Then `validate()` will return true or throw an exception\n        $valid = $validator-\u003evalidate(10000, $passphrase, $request-\u003eip());\n        \n        if (!$valid) {\n            echo $validator-\u003eerror();\n        }\n        \n        // validated!\n    }\n}\n```\n\n## Subscriptions\n\nSubscriptions are started in the same way as standard transactions. Simply add a call to `subscription()` on the `Transaction` instance:\n\n```php\n$transaction = new Transaction($merchant, 10000);\n$transaction-\u003esubscription();\n```\n\nThis will ensure the transaction is passed to PayFast as a recurring transaction. The `subscription` method also takes a few options to customise the subscription. You can specify the frequency, the number of cycles and the billing date:\n\n```php\n$transaction-\u003esubscription(\n    Transaction::SUBSCRIPTION_FREQUENCY_QUARTERLY,  // frequency\n    10,                                             // number of cycles\n    new DateTime('tomorrow'),                       // Billing start date\n);\n```\n\nPayFast supports four frequency options:\n\n```php\n$monthly = Transaction::SUBSCRIPTION_FREQUENCY_MONTHLY;  // default\n$quarterly = Transaction::SUBSCRIPTION_FREQUENCY_QUARTERLY;\n$biannually = Transaction::SUBSCRIPTION_FREQUENCY_BIANNUALLY;\n$annually = Transaction::SUBSCRIPTION_FREQUENCY_ANNUALLY;\n```\n\nThe `cycles` parameter defaults to 0 meaning indefinite. The subscription will continue until cancelled.\n\nOnce you've submitted the transaction, you can use the `token()` method on the `ItnValidator` instance to get a token reference for the transaction which can then be used to manage that subscription:\n\n```php\n$validator = new ItnValidator($request-\u003einput());\n\nif ($validator-\u003evalidate(10000, 'passphrase', $request-\u003eip()) {\n    $token = $validator-\u003etoken();\n}\n```\n\n### Fetching a subscription from PayFast\n\nYou can fetch details for any subscription using the `Subscription` class. Pass a `Merchant` instance as the first parameter and the subscription token as the second to the constructor and call the `fetch` method:\n\n```php\n$subscription = new Subscription($merchant, $token);\n$subscription-\u003efetch();\n\n$data = $subscription-\u003etoArray();\n```\n\nThere are number of features on the `Subscription` class which you can use to manage any subscription:\n\n### Pausing/Unpausing a subscription\n\nYou can pause a subscription for any number of cycles, but by default a subscription is paused for just 1. The next billing cycle will then be skipped. You get the next billing date using the `runDate` method on the `Subscription` object.\n\n```php\n$subscription-\u003epause();\n\n$subscription-\u003efetch()-\u003erunDate();  // Will skip the next billing date\n\n//---------------------------------------\n\n$subscription-\u003epause(2);\n\n$subscription-\u003efetch()-\u003erunDate(); // Will skip the next two billing dates\n```\n\nNote that PayFast does not allow you to alter the number of cycles paused here. You will need to `unpause` and then `pause` again with the new cycles.\n\nTo unpause a subscription, simply call the `unpause()` method:\n\n```php\n$subscription-\u003eunpause();\n```\n\nTo check if a subscription is paused, the `paused()` method will return true.\n\n```php\n$subscription-\u003epause();\n$subscription-\u003epaused();  // true\n```\n\n### Cancelling a subscription\n\nTo cancel a subscription, simply call the `cancel()` method:\n\n```php\n$subscription-\u003ecancel();\n$subscription-\u003ecancelled();  // true\n```\n\nPayFast retains the information about cancelled transaction, so even if you fetched data from a transaction that had been previously cancelled, you'll still get that transaction data, but `cancelled()` will return `true`.\n\n## Sandbox\n\nPayFast provides a simple sandbox against which transactions can be tested. The sandbox can be found at [https://sandbox.payfast.co.za](https://sandbox.payfast.co.za). In order to use the sandbox, you'll need to tell the library that you're testing. You can do so by calling the `testing()` method on the `Payfast` instance when creating a form:\n\n```php\n$payfast = new PayFast($transaction);\n\n$form = $payfast-\u003etesting()-\u003eform();\n```\n\nThis will ensure that requests are sent to the sandbox and not the actual PayFast endpoint. The same is true for the `ItnValidator`:\n\n```php\n$validator = new ItnValidator($request-\u003einput());\n$valid = $validator-\u003etesting()-\u003evalidate(10000, $passphrase, $request-\u003eip());\n```\n\nAnd when managing subscriptions:\n\n```php\n$subscription = new Subscription($merchant, 'TOKEN');\n$subscription-\u003etesting()-\u003epause();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftpg%2Fpayfast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftpg%2Fpayfast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftpg%2Fpayfast/lists"}