---
updatedAt: 2025-05-20T21:53:49.000Z
agentTools:
  projectIndex: https://shop-and-pay.readme.io/llms.txt
---

# Notifications (Webhooks)

## Changelog Version 2020-06-10

Transaction

* new attribute **amount** in smallest unit of the transaction currency. This amount will include the refunded amount for refund-webhooks

## Changelog Version 2019-12-19

Transaction:

* new status **uncaptured** (only with PSP **Clearhaus Acquiring**)

## Changelog Version 2019-10-15

Transaction:

* new attribute **preAuthorizationId** which contains the ID of the origin pre-authorized transaction (which had the status "authorized").
* new values for the **payment** attribute: cardNumber, expiry. This is only set for pre-authorized transactions or subscription payments.

General:

* Correct handling of zero-decimal currencies. All amounts are in the smallest unit of the currency. (e.g. 2 JPY => 2, 2 EUR => 200), before it would have been 200 for all currencies.

## Changelog Version 2019-07-16

New transaction status:

* a new status **refund\_pending** for transactions for which the refund has been initialized but not yet confirmed by the bank.

## Changelog Version 2019-02-13

Transaction statuses renamed:

* **chargeback dispute** to **chargeback**
* **Technical error** to **error**
* **Partially refunded** to **partially-refunded**

New Subscription status:

* a new status **in\_notice** for subscriptions which will not renew at the end of the period. In previous version it will appear as **cancelled** subscription.

Invoice gets new attributes:

* sku: stock keeping unit (string)
* vatRate: the vat rate in percentage (float)

## Events

Shop & Pay  webhooks will be fired on the following events.

**Transaction**

* Order placed (status: waiting)
* Successful payment processed (status: confirmed)
* Payment aborted by customer (status: cancelled)
* Payment declined (status: declined)
* Pre-authorization successful (status: authorized)
* Payment (partial-) refunded by merchant (status: refunded / partially-refunded), see [changelog](https://shop-and-pay.readme.io/docs/webhooks)
* Refund pending (status: refund\_pending), see [changelog](https://shop-and-pay.readme.io/docs/webhooks)
* Chargeback by card holder (status: chargeback), see [changelog](https://shop-and-pay.readme.io/docs/webhooks)
* Technical error (status: error), see [changelog](https://shop-and-pay.readme.io/docs/webhooks)

**Subscription**

* On successful payment of a subscription payment
* On failed payment of a subscription payment
* On cancelled subscription
* On noticed subscription (new by 2019-02-13, see [changelog](https://shop-and-pay.readme.io/docs/webhooks))

## Configuration

The configuration for the webhooks can be found at Integrations> Webhooks.\
There must be an accessible URL / IP address where the data should be sent to.\
You can choose which content type you want to use. "Normal (PHP-Post) means application/x-www-form-urlencoded and is best used for PHP-applications. "JSON" means application/json and is best used for all different applications.

<Image align="center" width="100%" src="https://files.readme.io/14abe66-Screenshot_2023-10-17_103920.png" />

## How to use

For an integration into a web shop you will create a [Shop & Pay Gateway](https://shop-and-pay.readme.io/docs/shop-and-pay-gateway). After the transaction has been performed, you will get a notification request to your server. You can identify the transaction by paymentLinkId or referenceId in [Invoice object](https://shop-and-pay.readme.io/docs/invoice-1).

## Data

The data will be either sent in [JSON format](https://en.wikipedia.org/wiki/JSON) or as [HTTP POST form-data](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST).

Depending on the information you want to track in your system, please go to the object specification:

* [Transaction](https://shop-and-pay.readme.io/docs/transaction)
* Subscription

## Examples

Currently we only have an example written in PHP.

Download full PHP example with a corresponding MySQL database: [click here to download](https://www.shop-and-pay.com/developers/examples/webhooks.zip)

```php
<?php

/**
 * The data of the POST request
 * @var array $transaction
 */
$transaction = !empty($_POST['transaction']) ? $_POST['transaction'] : array();

if (!empty($transaction)) {
		$invoice = $transaction['invoice'];
 	  $customFields = $invoice['custom_fields'];
 	  $contact = $transaction['contact'];
}
```