Download the PHP package code16/laravel-systempay without Composer

Systempay tools for Laravel

Features

• Fast and easy form generation for Systempay (by Banque Populaire)
• Support multiple site id for multiple stores within the same project
• Validate payment signature and status
• Cancel or refund a transaction (Using the API-REST)
• Retrieve a transaction's data (Using the API-REST)

[!NOTE] If you want to use this SystemPay client to cancel or refund transactions, you must create also a REST API key in the SystemPay Back Office.

Installation

1. Install the package

2. Publish the config file

Configuration

After publishing edit the default configuration file : config/systempay.php

You need to set YOUR_SITE_ID and YOUR_KEY with your own values. This two values are given by Systempay.

key is only used to sign/verify the payment form and IPN callbacks. To use cancel(), refund(), cancelOrRefund() (see Cancel or refund a payment) or getTransaction() (see Get a transaction), you also need to set rest.password, the REST API password found in the Back Office, under Paramétrage > Boutique > Clés d'API REST (use the test or production password depending on env).

Specific parameters

These parameters are set by default :

Also see Systempay documentation

NB : you don't have to add the vads_ prefix to parameters, the prefix will be automaticaly added. But you can also set the parameters with the vads_ prefix, it will be automaticaly removed.

NB : amount must be given as an integer in the smallest currency unit expected by Systempay (e.g. cents for EUR). For example, use 1234 for 12.34€, not 12.34. No unit conversion is performed by this package.

There is also possible to set some specific parameters to a configuration by setting params values.

Example :

In this case, default configuration will use the currency code 826.

Additional configuration

You can add as many configuration as you need by adding a new key to the configuration file.

For example :

To use another configuration, call the config method, for example :

IPN Callback

When a payment is processed, Systempay sends a POST request to your IPN URL (to be configured in your Systempay back office).

You can use the Systempay facade to validate the signature and check the payment status.

Webhook payload

formatWebhookPayload() looks up the signing key for the given configuration (default unless specified) and returns a Code16\Systempay\WebhookPayload object with the following read-only properties:

It also exposes validateSignature() and isValidPayment(), so the whole IPN payload — data and validation — comes from a single object.

Signature validation for specific configuration

If you have multiple configurations, pass the configuration name to formatWebhookPayload:

Customize valid payment status

By default, isValidPayment() returns true if the status is CAPTURED, ACCEPTED, or AUTHORISED. You can customize this by passing an array of valid statuses as the parameter:

Create a payment form

To create a payment form, you can use the Systempay facade.

In your controller :

In your view

Cancel or refund a payment

Use cancel() to cancel a transaction that has not been captured yet (i.e. before it is remised en banque), and refund() to refund a captured transaction, totally or partially. Both need the transaction uuid, as returned by formatWebhookPayload().

Both throw Code16\Systempay\Exceptions\SystemPayApiException if Systempay rejects the request (e.g. the transaction cannot be cancelled or refunded in its current state). The exception's response() method returns the decoded API response, including the errorCode returned by Systempay:

Under the hood, both call the Transaction/CancelOrRefund Web Service, which lets Systempay pick the operation automatically based on the transaction's status. You can call it directly and force the operation with resolutionMode (AUTO, CANCELLATION_ONLY or REFUND_ONLY):

As with validateSignature, pass a configuration name as the last argument to target a specific store:

Get a transaction

Use getTransaction() to retrieve all the data Systempay holds for a transaction, identified by its uuid (as returned by formatWebhookPayload()):

It calls the Transaction/Get Web Service and, like cancel()/refund(), throws SystempayApiException if Systempay rejects the request, and accepts a configuration name as the second argument: