Notifications

After the completion of a transaction we will notify you in two ways:

1. Via the Front-Channel using the notification URLs

2. Via the Back-Channel using the CallBack URL

Via the Front-Channel

The notifications via the front-channel are primarily to have a logical ending of the payment flow for the payee and create a positive user experience. You can for instance consider to let the payee land on a thank-you page after successfully completing a payment. Of course you can update the status of the transaction using this page, but you can't totally rely on the payee actually visiting this page and not closing the browser.

Via the Back-Channel

To make sure that you always receive the right status of the transaction we also send a notification to your CallBack URL. You can set this CallBack URL in your merchant dashboard under 'Channels'. You can also set this value in the notification object in your payment request:

"notification": { "callbackUrl": "https://yourcallbackurl.nl", "successUrl": "https://yoursuccessurl.nl", "failedUrl": "https://yourfailedurl.nl", "cancelledUrl": "https://yourscancelledurl.nl", "expiredUrl": "https://yourexpiredurl.nl", "rejectedUrl": "https://yoursrejectedurl.nl" }

The value in your payment request will prevail over the value set in the merchant dashboard.

When the CallBackURL is set we will send a notification with the following structure to this URL:

{ "id": "754eaa98-c7ed-493d-a94b-5697ba134fd5", "amount": 0.25, "currency": "EUR", "dateCreated": "2024-09-17T21:03:04.806Z", "state": "rejected", "issue": "MS03", "method": "sepa", "description": "The payment has been announced to be chargedback", "reference": "merchant reference", "type": "donation", "action": "pay" }

You can use both our UUID (id) or your reference in this message to update the status.

The state of the transaction can be one of the following (Status - Status Code - Notification):

Success - 200 to 299 - processed

Failed - 300 to 399 - failed

Cancelled - 400 to 499 - cancelled

Rejected - 500 to 599 - rejected

Expired - 600 to 699 - expired

Pending - 700 to 799 - pending

In case of the status 'Cancelled' the notification will also include the field issue. This field can contain the following values:

AC04 - The specified bank account has been closed

MD07 - The customer is deceased

AC06 - The specified account is blocked. No transactions can be booked for this account

AM04 - The amount of funds available to cover the specified transaction was insufficient

MD06 - The customer requested a chargeback

MD01 - No existing mandate was found

The notification service is secured by a handshake key. You can add this key to your channel via the payment dashboard. This key will be sent in the header of each payment notification in the key 'X-Handshake-Key'.

If you need more information about the status of the payment, please use the payment status endpoint: https://better-world.readme.io/reference/getpaymentstatus