Using the IPN (notification URL)

IPN stands for Instant Payment Notification. When a transaction is created or its status changes, our servers issue an IPN calling a Notification URL located on your servers. This allows you to be notified in real time about the changes that affected the transaction.

Fore more general information on the IPN, see the following article: IPN: background information

An IPN is the only way to be notified in the following cases:

• The buyer has lost Internet connection
• The buyer closed their browser during the payment
• Transaction is rejected
• The buyer did not complete their payment before the expiration of the payment session

Therefore, it is imperative to integrate IPNs!

Operating principle

When the Buyer validates the payment, a transaction is created. Our servers will attempt to communicate with your servers to transmit all the information concerning the transaction.

Step 3 occurs only after your servers have responded (the maximum delay is 30 seconds). This allows you to update your information system before the Buyer is redirected to your purchase confirmation page.

Define the URL in the Expert Back Office

End of Payment Notification

The end of payment notification allows the merchant website to be notified in the following cases:

• Payment accepted
• Payment refused
• Token created or updated
• Recurring payment created

To configure the notification:

1. Login to the Lyra Collect Back Office
2. Go to the following menu: Settings > Notification rules.
3. Right-click Instant Payment Notification.
4. Select Manage the rule.
5. In the General settings section, enter the E-mail address(es) to notify in case of failure.
6. Check the Automatic retry in case of failure checkbox if you want to allow the gateway to automatically resend the notification in case of failure (can be resent up to 4 times).
7. In the IPN URL section of the REST API, enter your page URL in the fields Target URL of the IPN to notify in TEST mode and Target URL of the IPN to notify in PRODUCTION mode.
8. Save the changes.

If the target server of the IPN is offline, an e-mail will be sent to the address you specified in rule configuration.

This e-mail contains:

• The HTTP error code returned by your server
• Elements of analysis
• Explanation of the error's consequences
• Instructions for resending the IPN (via the Expert Back Office)

Notification in case of abandonment

The notification of payment abandonment allows to notify the merchant website when the buyer has not completed their payment before their payment session expires.

In this case, the notification does not contain a Transaction object, but simply the Order details.

Special case of cardholder authentication

In case of abandonment during the authentication process, the merchant website receives:

• An end of payment notification to notify about the payment rejection that contains a Transaction object with the details of the refused payment.
• An abandonment notification, containing the order details.

By default, the merchant site is not notified in case of abandonment. you must enable the corresponding notification rule in your Lyra Collect Back Office.

To configure the notification:

1. Login to the Lyra Collect Back Office
2. Go to the following menu: Settings > Notification rules.
3. Right-click on Instant Payment Notification URL on cancellation.
4. Select Manage the rule.
5. In the General settings section, enter the E-mail address(es) to notify in case of failure.
6. Check the Automatic retry in case of failure checkbox if you want to allow the gateway to automatically resend the notification in case of failure (can be resent up to 4 times).
7. In the IPN URL section of the REST API, enter your page URL in the fields Target URL of the IPN to notify in TEST mode and Target URL of the IPN to notify in PRODUCTION mode.
8. Save the changes.
9. Enable the rule by right-clicking Instant Payment Notification URL on cancellation and selecting Enable the rule.

Specifying the URL dynamically

When creating the formToken, you can dynamically specify the target URL of the IPN using the ipnTargetUrl parameter:

{
    "amount": 990,
    "currency": "EUR",
    "ipnTargetUrl": "https://my.super.site/ipn"
}

Using IPNs

The IPN is sent to your servers using the same procedure as the JavaScript client. This allows you to use similar code for processing the response:

• The data is sent as a form (content-type: x-www-form-urlencoded).
• The parameters that contain data are the same.

The differences are:

• kr-answer contains complete Transaction objects.
• The signature included in kr-hash is calculated differently.

The IPN is sent to your servers via POST as follows:

kr-hash=c3c0323c748fdb7c2d24bd39ada99663526236828efa795193bebfdea022fe58
kr-hash-algorithm=sha256_hmac
kr-hash-key=password
kr-answer-type=V4/Payment
kr-answer={"shopId":"33148340","orderCycle":"CLOSED",(...)}

The POST parameters correspond to:

Before analyzing the contents of kr-answer, we must check if it is valid.

Verifying the IPN signature (hash)

In order to detect potential fraud, you must verify the authenticity of the kr-answer field.

The kr-hash field contains the kr-answer hash generated with the password (that starts with testpassword or prodpassword).

The password is available in your Back Office ( Settings menu > Shop, REST API keys tab, REST API keys section).

To verify the validity of the signature with our SDKs:

/* Check the signature using password */

if (!$client->checkHash()) {
    //something wrong, probably a fraud ....
    signature_error($formAnswer['kr-answer']['transactions'][0]['uuid'], $hashKey, 
                    $client->getLastCalculatedHash(), $_POST['kr-hash']);
    throw new Exception('invalid signature');
}

Once the signature has been checked, you can retrieve the information related to the transaction as follows:

/* Retrieve the IPN content */
$rawAnswer = $client->getParsedFormAnswer();
$formAnswer = $rawAnswer['kr-answer'];

/* Retrieve the transaction id from the IPN data */
$transaction = $formAnswer['transactions'][0];

/* get some parameters from the answer */
$orderStatus = $formAnswer['orderStatus'];
$orderId = $formAnswer['orderDetails']['orderId'];
$transactionUuid = $transaction['uuid'];

See the next section for more information.

Example of implementing hash verification in PHP:

    /**
     * check kr-answer object signature
     */
    public function checkHash($key=NULL)
    {
        $supportedHashAlgorithm = array('sha256_hmac');

        /* check if the hash algorithm is supported */
        if (!in_array($_POST['kr-hash-algorithm'],  $supportedHashAlgorithm)) {
            throw new LyraException("hash algorithm not supported:" . $_POST['kr-hash-algorithm'] .". Update your SDK");
        }

        /* on some servers, / can be escaped */
        $krAnswer = str_replace('\/', '/', $_POST['kr-answer']);

        /* if key is not defined, we use kr-hash-key POST parameter to choose it */
        if (is_null($key)) {
            if ($_POST['kr-hash-key'] == "sha256_hmac") {
                $key = $this->_hashKey;
            } elseif ($_POST['kr-hash-key'] == "password") {
                $key = $this->_password;
            } else {
                throw new LyraException("invalid kr-hash-key POST parameter");
            }
        }
    
        $calculatedHash = hash_hmac('sha256', $krAnswer, $key);
        $this->_lastCalculatedHash = $calculatedHash;

        /* return true if calculated hash and sent hash are the same */
        return ($calculatedHash == $_POST['kr-hash']);
    }
}

The choice of the key must be based on the value of kr-hash-key:

Transaction object

The Transaction object is contained in the kr-answer POST parameter in JSON format:

The kr-answer parameter contains information about the status of the payment session:

{
    "shopId": "69876357",
    "orderCycle": "CLOSED",
    "orderStatus": "PAID",
    "serverDate": "2018-09-27T14:02:17+00:00",
    "orderDetails": (...)
    "customer": (...)
    },
    "transactions": [{
        "shopId": "69876357",
        "uuid": "5b158f084502428499b2d34ad074df05",
        "amount": 990,
        (...)
        "_type": "V4/PaymentTransaction"
    }],
    "_type": "V4/Payment"
}

You can use any standard function to access it, or use our SDK:

/* Retrieve the IPN content */
$rawAnswer = $client->getParsedFormAnswer();
$formAnswer = $rawAnswer['kr-answer'];

/* Retrieve the transaction id from the IPN data */
$transaction = $formAnswer['transactions'][0];

/* get some parameters from the answer */
$orderStatus = $formAnswer['orderStatus'];
$orderId = $formAnswer['orderDetails']['orderId'];
$transactionUuid = $transaction['uuid'];

Transaction lifecycle

To understand the meaning of the status and detailedStatus fields, go to: Status reference.

Merchant server restrictions

If a restriction is set up on the Merchant side, the IP address range 194.50.38.0/24 will have to be authorized.

Notifications are sent from an IP address in the 194.50.38.0/24 range in Test and Production mode.