swish-php

KO | EN

gitlite — search

#python #ai #machine-learning #linux #nodejs #java #awesome #cli #kubernetes #awesome-list #mcp #ios #openai #open-source

(★ 31)

Swish API-wrapper for PHP and Laravel

swish-php 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Swish PHP

[![Supported PHP-versions](https://img.shields.io/packagist/php-v/olssonm/swish-php?style=flat-square)](https://packagist.org/packages/olssonm/swish-php)
[![Latest Version on Packagist](https://img.shields.io/packagist/v/olssonm/swish-php.svg?style=flat-square)](https://packagist.org/packages/olssonm/swish-php)
[![Build Status](https://img.shields.io/github/actions/workflow/status/olssonm/swish-php/test.yaml?branch=main&style=flat-square)](https://github.com/olssonm/swish-php/actions?query=workflow%3A%22Run+tests%22)
[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](https://raw.githubusercontent.com/olssonm/swish-php/main/LICENSE.md)

The leading Swish API-wrapper for PHP: minimal setup, rigorous tests, and Laravel providers built in.

## Prerequisites

This package supports PHP ^8.2. Tested against Laravel 11 & 12. 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. Note however that Payouts are available from v3.*

## 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 Simulator environment without being a Swish-customer during development.

Read more about testing in their MSS-environment in their [official documentation](https://developer.swish.nu/documentation/environments#merchant-swish-simulator). A quick rundown on using/creating Swish-certificates [is published here](https://marcusolsson.me/artiklar/hur-man-skapar-certifikat-for-swish) (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:

``` php
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/
```

``` php
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:

``` php
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 your payee-alias, callback-url and such, which you can then access with `config('swish.payee_alias')` etc.

For convenience and security, you can use relative paths to reference your certificates. Laravel will automatically resolve these paths from the `storage/app/private` directory.

```env
SWISH_CLIENT_CERTIFICATE_PATH=swish/client.pem # storage/app/private/swish/client.pem
```

If you prefer to keep your certificates in a specific location outside the default storage directory, you can provide an absolute path. However, be aware that when using an absolute path, the package will not utilize the filesystem to resolve the relative path.

```env
SWISH_CLIENT_CERTIFICATE_PATH=/absolute/path/swish/client.pem
```

## Usage

A typical case for creating a Swish-payment.

``` php
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`)

```php
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',
]));
```

*The easiest way to see more complete examples is to look at the tests; in [MMS.php](/tests/MMS.php) all major examples are covered.*

### Payments and Refunds

> [!TIP]
> Read more about [payments](https://developer.swish.nu/api/payment-request/v2) and [refunds](https://developer.swish.nu/api/refunds/v2) in the official documentation

Always when using the client, use the Payment and Refund-classes <u>even if only the ID is needed for the action</u>, i.e:

``` php
$payment = $client->get(new Payment(['id' => '5D59DA1B1632424E874DDB219AD54597']));
```

### QR-codes

QR codes is another way that users can pay – using them they do not need to supply their phone number. This also makes it possible to pay using POS terminals and such, which may lack any input-methods such as a keyboard or touch screen.

***Note** This package creates QR-codes according to the [Mcom to Qcom](https://developer.swish.nu/api/qr-codes/v1#mcom-to-qcom)-flow. While Swish provides endpoints to create "prefilled QR-codes" and more, they lack the ability to automatically verify payments which makes them unsuitable for web applications and therefore is outside the scope of this package.*

Creating QR-codes requires two requests to the Swish API; first to create the payment and retrieve the payment request token, and then a separate request to get a QR code. Create the payment as usual, but *exclude the payerAlias* (users phone number); else the QR-endpoint will fail.

``` php
use Olssonm\Swish\Payment;
use Olssonm\Swish\QR;

// Create payment
$payment = new Payment([
    'callbackUrl' => 'https://callback.url',
    'payeePaymentReference' => 'XVY77',
    'payeeAlias' => '123xxxxx',
    'amount' => '100',
    'currency' => 'SEK',
    'message' => 'A purchase of my product',
]);

$paymentResponse = $client->create($payment);

// Create QR code
$qr = new QR([
    'token' => $paymentResponse->paymentRequestToken
]);

$qrResponse = $client->create($qr);
```

With this response you could for instance save the image:

``` php
file_put_contents(__DIR__ . '/swish/qr.png', $qrResponse->data);
```

Or output it as base64 with the included helper:

``` php
<img src="<?php echo $qrResponse->toBase64(); ?>" />
```

### Payouts

> [!TIP]
> Read more about [payouts](https://developer.swish.nu/api/payouts/v1) in the official documentation

Payouts need to be hashed using SHA-512 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:

``` php
$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:

``` php
$certificate = new Certificate(/**/);
$payout = new Payout([
    'signingCertificateSerialNumber' => $certificate->getSerial()
])
```

Or assign it yourself ([see gist for extracting serial](https://gist.github.com/olssonm/7da7d35dff2ec3ae74d0d0439003913c)):

``` php
$payout = new Payout([
    'signingCertificateSerialNumber' => '4512B3EBDA6E3CE6BFB14ABA6274A02C'
])
```

> [!IMPORTANT]  
> Note that Payouts use `payoutInstructionUUID` instead of an `ID`, you should [set this yourself to keep track of it](#regarding-idsuuids). 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):

``` php
$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](https://github.com/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 <u>always</u> 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, as well as refunds can be created and retrieved. All of them are performed via `Olssonm\Swish\Client`;

### 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.

```php
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`-errors a `\Olssonm\Swish\Exceptions\ClientException` will be thrown, and for `5xx`-errors `\Olssonm\Swish\Exceptions\ServerException`. Both of these implements Guzzle's `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:

```php 
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 retrieves the current HTTP-request (via `file_get_contents('php://input')`). You may however inject your own data if needed (or if you for example have a Laravel request-object ready):

```php
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](https://developer.swish.nu/documentation/environments).

## Testing and contributing

Testing is done via pest. Simply run `composer test` to run them.

I take pride knowing that all code is tested and aim for 100% test coverage. If you want to contribute, please make sure to add tests and to make sure that no tests fail.

## License

The MIT License (MIT). Please see the [LICENSE](LICENSE) for more information.

swish-php

swish-php 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

swish-php

swish-php 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README