olssonm / swish-php
Swish API-wrapper. Compatible with Laravel
Fund package maintenance!
olssonm
marcusolsson.me/kontakta
Installs: 8 971
Dependents: 0
Suggesters: 0
Security: 0
Stars: 18
Watchers: 3
Forks: 1
Open Issues: 0
Requires
- php: ^8.1
- guzzlehttp/guzzle: ^6.3.1 || ^7.0
- nesbot/carbon: ^2 || ^3
- ramsey/uuid: ^4.2
Requires (Dev)
- ergebnis/composer-normalize: ^2.43
- orchestra/testbench: ^8.0 || ^9.0
- pestphp/pest: ^1.0 || ^2.0
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^8.3 || ^9.3 || ^10.0
- squizlabs/php_codesniffer: ^3.5
Suggests
- illuminate/contracts: Required to use the Laravel integration (^10.0|^11.0).
- illuminate/support: Required to use the Laravel integration (^10.0|^11.0).
This package is auto-updated.
Last update: 2024-09-12 20:23:55 UTC
README
A simple and easy to use wrapper for the Swish-API in PHP. Also includes providers and facades for quick setup with Laravel.
Prerequisites
This package supports PHP ^8.1. Tested against Laravel 10 & 11. PHP needs to be compiled with the cURL and SSL extensions (in an absolute majority of cases, they should be available by default).
Using an older version of PHP or Laravel? Check out v1 and v2 of this package.
Installation
composer require olssonm/swish-php
Setup
You will need to have access to your Swish-certificates to use this package in production. You can however use their testing/Merchant Swish Similator-environment without being a Swish-customer during development.
Read more about testing in their MSS-environment in their official documentation. A quick rundown on using/creating Swish-certificates is published here (in Swedish).
When creating the client, you will have to set which environment you are working with (otherwise it defaults to the production environment, https://cpc.getswish.net/swish-cpcapi/api/
), you may use any of the following options:
Client::TEST_ENDPOINT // https://mss.cpc.getswish.net/swish-cpcapi/api/ Client::PRODUCTION_ENDPOINT // https://cpc.getswish.net/swish-cpcapi/api/ Client::SANDBOX_ENDPOINT // https://staging.getswish.pub.tds.tieto.com/swish-cpcapi/api/
use Olssonm\Swish\Certificate; use Olssonm\Swish\Client; $certificate = new Certificate( '/path/to/client.pem', 'client-passphrase', '/path/to/root.pem', // Can also be omitted for "true" to verify peer '/path/to/signing.key', // Path to signing certificate, only used for payouts 'signing-passphrase' // Only used for payouts ); $client = new Client($certificate, $endpoint = Client::TEST_ENDPOINT)
Important
The paths to the certificates should be absolute. You can use realpath -s YOUR_CERT.pem
for this.
Laravel
With the Laravel service provider and facades you can work with the package more eloquently. Just require the package and publish the configuration:
php artisan vendor:publish --provider="Olssonm\Swish\Providers\SwishServiceProvider"
In /config/swish.php
, you can then set your details accordingly:
return [ 'certificates' => [ 'client' => env('SWISH_CLIENT_CERTIFICATE_PATH'), 'password' => env('SWISH_CLIENT_CERTIFICATE_PASSWORD'), 'root' => env('SWISH_ROOT_CERTIFICATE_PATH', true), 'signing' => env('SWISH_SIGNING_CERTIFICATE_PATH', null), 'signing_password' => env('SWISH_CLIENT_SIGNING_PASSWORD', null), ], 'endpoint' => env('SWISH_URL', \Olssonm\Swish\Client::PRODUCTION_ENDPOINT), ];
This may also be a good place to keep you payee-alias, callback-url and such, which you can then access with config('swish.payee_alias)
etc.
Usage
A typical case for creating a Swish-payment.
use Olssonm\Swish\Certificate; use Olssonm\Swish\Client; use Olssonm\Swish\Payment; $certificate = new Certificate( '/path/to/client.pem', 'client-passphrase' ); $client = new Client($certificate); // Create a new payment-object $payment = new Payment([ 'callbackUrl' => 'https://callback.url', 'payeePaymentReference' => 'XVY77', 'payeeAlias' => '123xxxxx', 'payerAlias' => '321xxxxx', 'amount' => '100', 'currency' => 'SEK', 'message' => 'A purchase of my product', ]); // Perform the request $response = $client->create($payment); // $response->id = '11A86BE70EA346E4B1C39C874173F088' // $response->location = 'https://mss.cpc.getswish.net/swish-cpcapi/api/v1/paymentrequests/11A86BE70EA346E4B1C39C874173F088' // $response->paymentRequestToken = 'a-unique-token'
With Laravel you can also use the facade and save a few lines of code (in this example Olssonm\Swish\Facades\Swish
has been aliased to Swish
)
use Swish; use Olssonm\Swish\Payment; $response = Swish::create(new Payment([ 'callbackUrl' => 'https://callback-url.com', 'payeePaymentReference' => 'XVY77', 'payeeAlias' => '123xxxxx', 'payerAlias' => '321xxxxx', 'amount' => '100', 'currency' => 'SEK', 'message' => 'My product', ]));
Payments and Refunds
Tip
Read more about payments and refunds in the official documentation
Always when using the client, use the Payment and Refund-classes even if only the ID is needed for the action, i.e:
$payment = $client->get(Payment(['id' => '5D59DA1B1632424E874DDB219AD54597']));
Payouts
Tip
Read more about payouts in the official documentation
Payouts need to be hashed using SHA512 and signed with a signing certificate before being sent to Swish – don't worry though, this package will handle most of this automatically. Just make sure that the path to your signing certificate is set:
$certificate = new Certificate( '/path/to/client.pem', 'client-passphrase', true, '/path/to/signing.key', 'signing-passphrase' ); $client = new Client($certificate); $payout = $client->create(new Payout([]));
Additionally your certificate's (note: your signing certificate, not your client certificate) serial needs to be supplied. You can either use the Certificate
-class to handle on the fly:
$certificate = new Certificate(/**/); $payout = new Payout([ 'signingCertificateSerialNumber' => $certificate->getSerial() ])
Or assign it yourself (see gist for extracting serial):
$payout = new Payout([ 'signingCertificateSerialNumber' => '4512B3EBDA6E3CE6BFB14ABA6274A02C' ])
Important
Note that Payouts uses payoutInstructionUUID
instead of an ID
, you should set this yourself to keep track of it. If it's missing, it will be set automatically upon creation.
Regarding IDs/UUIDs
This package uses the v2 of the Swish API where a UUID is set by the merchant. This package handles all these aspects automatically as needed, you may however choose to manually set the ID/instructionUUID (either in Swish's own format, or a default v4-format):
$id = 'EBB5C73503084E3C9AEA8A270AEBFE15'; // or $id = 'ebb5c735-0308-4e3c-9aea-8a270aebfe15'; $payment = new Payment([ 'id' => $id ]);
When generating the UUIDs on the fly, the package uses Ramsey/Uuid to generate RFC4122 (v4) UUIDs. Swish accepts V1, 3, 4 and 5 UUIDs if you chose to set your own UUIDs.
If an invalid UUID is used, a Olssonm\Swish\Exceptions\InvalidUuidException
will be thrown.
Note
No matter if you set your own UUID och let the package handle the generation, the UUID will always be formatted for Swish automatically (dashes removed and in uppercase).
Available methods
This package handles the most common Swish-related tasks; retrieve, make and cancel payments. Retrieve and create payouts, aswell as refunds can be created and retrieved. All of them are performed via Olssonm\Swish\Client
;
$client->get(Payment $payment | Refund $refund | Payout $payout); $client->create(Payment $payment | Refund $refund | Payout $payout); $client->cancel(Payment $payment);
Exception-handling
When encountering a validation-error an Olssonm\Swish\Exceptions\ValidationException
will be thrown. The Object will contain both the request, response as well as the getErrorCode()
and
getErrorMessage()
-helpers.
try { $response = $client->create($payment); } catch (ValidationException $exception) { $errors = $exception->getErrors(); foreach ($errors as $error) { $error->errorCode; // AM03 $error->errorMessage; // Invalid or missing Currency. } }
For 4xx
-error a \Olssonm\Swish\Exceptions\ClientException
will be thrown, and for 5xx
-errors \Olssonm\Swish\Exceptions\ServerException
. Both of these implements Guzzles BadResponseException
which makes the request- and response-objects available if needed.
Callbacks
Swish recommends to not use the payments
-endpoint to get the status of a payment or refund (even if they themselves use it in some of their examples...), but instead use callbacks.
This package includes a simple helper to retrieve a Payment
, Refund
or Payout
object from a callback that will contain all data from Swish:
use Olssonm\Swish\Callback; $paymentOrRefund = Callback::parse(); // get_class($paymentOrRefund) = \Olssonm\Swish\Payment::class, \Olssonm\Swish\Refund::class, \Olssonm\Swish\Payout::class
The helper automatically retrieve the current HTTP-request (via file_get_contents('php://input')
). You may however inject your own data if needed (or if you for example has a Laravel request-object ready):
class SwishController { public function Callback(Request $request) { $data = Callback::parse($request->getContent()); if(get_class($data) == \Olssonm\Swish\Payment::class) { // Handle payment callback } else if(get_class($data) == \Olssonm\Swish\Refund::class) { // Handle refund callback } else if(get_class($data) == \Olssonm\Swish\Payout::class) { // Handle payout callback } } }
In a real world scenario you probably want to use separate callback-urls for your refunds, payouts and payments to prevent unnecessary parsing as the example above.
Caution
Please note that the callback from Swish is not encrypted or encoded in any way , instead you should make sure that the callback is coming from a valid IP-range.
License
The MIT License (MIT). Please see the LICENSE for more information.
© 2022-2024 Marcus Olsson.