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
Annanow 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
- Refund pending (status: refund_pending), see changelog
- Chargeback by card holder (status: chargeback), see changelog
- Technical error (status: error), see changelog
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)
Configuration
The configuration for the webhooks can be found at Settings > API.
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.
How to use
For an integration into a web shop you will create a Annanow 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.
Data
The data will be either sent in JSON format or as HTTP POST form-data.
Depending on the information you want to track in your system, please go to the object specification:
- 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
<?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'];
}
Updated over 3 years ago