During the payment process our system generate server side events and your site must be aware of these events. Every time the eGiftCertificate is updated your site will receive a notification with current status.

The IPN notification works like a webhook and you receive a POST request with a JWT in the body, the JWT contains information about the order and the certificate.

IPN example:

POST https://yoursite.com/ipn_handler

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIwMDAxMjM0NSIsImlzcyI6IjQyNjBGRTBFMDU3RjAzMDYwO
Tc2IiwiaWF0IjoxNTUzMTgzMjU2LCJleHAiOjE1NTMxODY4NTYsIm9yZGVyTnVtYmVyIjoiMTIzNDU2NzgiLCJhbW91bnQ
iOiIyMC41MCIsInBpbiI6IlZZUEEtRVBSNy1JQkNLLTlBVEMiLCJzdGF0dXMiOiJTT0xEIn0.9hd--y1Y6YrGKaq_sfv3u
UiRN3TLIe2zwivK9cZDJbo

The token is signed using the same API Key used to create the Authentication token during the checkout process. You must ensure verify and decode the received token with that API Key.

Because the API KEY is only know by you and Pay’nUp if you receive a token with invalid signature must reject the token instantly.

Once the token is decoded the content is something like this:

{
  "jti": "00012345",
  "iss": "4260FE0E057F03060976",
  "iat": 1553183256,
  "exp": 1553186856,
  "orderNumber": "12345678",
  "amount": "20",
  "total": "21.50",
  "pin": "VYPA-EPR7-IBCK-9ATC",
  "status": "SOLD"
}

You can receive more than one notification in your handler, during the sold and during the PIN redemption.

PIN Status process:

• SOLD: The transaction has been completed in Pay’nUp and the PIN has been sold to the customer but the PIN has not been redeemed yet.
• USED: The PIN has been redeemed and your order can be marked as completed.

Can try the integration without a simple line of code using the eGiftCertificate integration toolbox and https://webhook.site to listen incoming events.

Example

The following example demonstrate the use of the IPN handler inside an existent application.

<?php
use \Firebase\JWT\JWT;

$token = @file_get_contents('php://input');

try {
    $payload = JWT::decode($token, $this->apiKey, ['HS256']);
} catch (\Exception $exception) {
    wp_die($exception->getMessage(), 'eGiftCertificate IPN', ['response' => 500]);
    exit;
}
 
if (isset($payload->orderNumber)) {
    $order = wc_get_order($payload->orderNumber);

    if ($payload->iss !== $this->apiID
        || !$order
        || $payload->amount != $order->get_total()
    ) {
        wp_die('IPN does not match with any existent order', 'eGiftCertificate IPN', ['response' => 500]);
    }

    if ($payload->status === 'SOLD') {
        $order->add_order_note(sprintf('eGiftCertificate obtained: %s', $payload->pin));
    }

    if ($payload->status === 'USED') {
        $order->add_order_note('eGiftCertificate validated & redeemed successfully');
        $order->payment_complete($payload->pin);
    }
} else {
    wp_die('Invalid IPN Payload', 'eGiftCertificate IPN', ['response' => 500]);
}

IMPORTANT: Always check if the amount of the purchased and redeemed eGiftCertificate match with your order total.

Accepted Response

The webhook must return a valid http status code to know if the notification has been accepted or rejected.

• 2×× Success any status code with 2xx is treated as accepted, and the checkout must continue.
• 410 Gone - the payment can’t be accepted because the resource you are trying to purchase is not available, and the payment must be refunded. Optionally can response with a text message in the body to display that message to the customer in the payment page.

If your server fails to respond with any of the above status code, Pay’nUp will resend this IPN either until a valid code is received or up to 5 times.