Partner Notifications

Updated 9 Days AgoPublic

Actions

Partner Notifications

Handling notification on partner side

Handling retrieved notifications involves the following steps:

1. Verify if the notification has been sent by PV2.
2. Check if the notification has already been handled.
3. Confirm the handling of the given notification.

Ways to Handle Notifications

1. Handling Notifications Using the PV2 Endpoint (Not Recommended)

To meet all requirements, you can call the notification.hash.validation endpoint. This endpoint requires the hash of the given notification as an argument. It will return success only if:

• The given hash exists on the PV2 side, and
• The notification has a status of “not handled.”
• At the same time, the endpoint will mark the notification as “handled.”

Why is this approach not recommended?
The processes of verification (Step 1) and handling confirmation (Step 2) cannot be separated. If you simply want to verify the notification, it will still be marked as “handled.” This can cause issues because, in the event of an exception during processing, the PV2 system will never reattempt the notification (since handled = 1).

2. Handling Notifications Using the PV2 Endpoint with the verify-only Flag

Verify the Notification & Check if the Notification Has Been Handled
In this case, you use the notification.hash.validation endpoint with an additional verify-only flag. To do this, append verify-only=1 to your request.

This approach performs the same checks as before (exists on PV2 and is not already handled), but does not set the notification to “handled.”

This allows you to cover Steps 1 and 2 without finalizing the notification as handled.

Confirm Handling of the Notification
To fulfill Step 3, the callback script retrieving the notification should print the predefined output, ensuring the content of the returned response is plain text: *NOTIFIED*.

3. Handling Notifications Without Using the PV2 Endpoint

In this case, all required steps are handled on the partner's side.

Verify the Notification
To handle notifications of this type, you need to define a verification secret string. This value (e.g., an MD5 result) must be configured on the PV2 side (in the notification URL settings) and will be used to generate an extra hash that is appended to the notification.

A sample structure for the notification object:

{
    "command": "...",
    "hash": "....",
    "data": {
        ...
    },
    "verify": "f75e721c6ff19ffcfd060a7d0ff02424407eb6a832d29196969d6bf844562571"
}

If the verify key exists, you need to generate your own verification hash on the partner side. To do this, use the following:

hash_hmac('sha256', json_encode($notification), $secretKey);

where $notification is an array built from the passed notification data:

$notification = [
    'command' => $command,
    'hash' => $hash,
    'data' => $data
];

$secretKey is your verification secret.

The resulting hash should match the verify value passed in the notification. If they match, the notification is confirmed as coming from the PV2 app.

Check if the Notification Has Been Handled
On the partner's side, you need to implement a mechanism to track successfully processed hashes (e.g., an additional database table).

Confirm Handling of the Notification
You can use the same mechanism as described in Handling Notifications Using the PV2 Endpoint with the verify-only Flag. When a notification is successfully handled, print the predefined output: *NOTIFIED*.

4. Asynchronous Notification Processing

To build an asynchronous solution using the notification.hash.validation endpoint:

The callback URL should add the notification to an internal async mechanism and return a blank output.
A consumer process that performs the actual processing should call notification.hash.validation without the verify-only flag.

Note: This approach introduces a potential risk due to the time gap between receiving the notification and running the processing script. To mitigate this, consider using an additional table to manage processing hashes.

bold text

List of notifications

transaction.success
transaction.failed
transaction.change
subscription.created
subscription.trial
subscription.stopped
subscription.suspended
subscription.rebill
subscription.completed
subscription.change

PV2 is sending notifications to our partners regarding various actions on PV2. Notifications are always sent to the same URL defined for each partner along with hash and other related data. If partner doesn't respond to notification, PV2 will try to resend it.

Generally notifications will be sent in this format:

When partner receives a notification the next step should be confirmation. There are two ways to do that.

• notifications.hash.validate api call (async) by sending received hash back
• return a given string '*NOTIFIED*' as a result of notification request (http code must be 200)

For non confirmed notifications the resend mechanism will retry notification according to below schedule:

1. After 1 minute
2. After 5 minutes
3. After 15 minutes
4. After 30 minutes
5. After 30 minutes

notifications.hash.validate call also has another important purpose, so partners can validate if the notification actually came from us.

This is list of notifications which will be send out.

transaction.success

Sent in case of successful transaction.

Data array (json encoded)

*Processor dependant, may not be sent for all processors - currently only RocketGate and Payon use this field
For RocketGate transaction, merchant is [merchant_id, merchant_account], for Payon it is [channel]
For RocketGate transaction, only when using already existing card (rebills/rejoins)

transaction.failed

Sent in case of failed transaction.

Data array (json encoded)

*Processor dependant, may not be sent for all processors - currently only RocketGate and Payon use this field
For RocketGate transaction, merchant is [merchant_id, merchant_account], for Payon it is [channel]
For RocketGate transaction, only when using already existing card (rebills/rejoins)

transaction.change

Sent when transaction has been changed.
Possible cases when that might happen:

• transaction.delete_chargeback
• transaction.chargeback refund for the same transaction already exists. so we update Refund -> Chargeback

Data array (json encoded)

*Processor dependant, may not be sent for all processors - currently only RocketGate

subscription.created

Sent when subscription is successfully created and subscription does not have trial.
Subscription does not have trial, if appropriate item passed in transaction.init call, have empty value for parameter trial_period.
(Minor use case: Also sent for manually rebilled subscriptions, in this case value of rebill_period for appropriate item in transaction.init call should be -1)

Data array (json encoded)

* Not present for all payment processors

subscription.trial

Sent when subscription is successfully created and subscription does have trial.
Subscription does have trial, if appropriate item passed in transaction.init call, have non-empty value for parameter trial_period.

* Not present for all payment processors

subscription.stopped

Sent in case of stopped subscription (action initiated via api call)

Data array (json encoded)

subscription.suspended

Sent in case of suspended subscription (usually happens when we can't rebill user after defined number of attempts)

Data array (json encoded)

subscription.rebill

Sent after successfully made rebill. It will be sent right after transaction.success

Data array (json encoded)

* Not present for all payment processors

subscription.completed

Sent after completed subscription (happens only on subs with limited number of rebills).

Data array (json encoded)

subscription.change

Sent in when subscription is changed (action initiated via subscription.change api call)

Data array (json encoded)