IPN POST

Example Response

<?php
$_POST = [
    'event'                             => 'subscription-payment',
    'mode'                              => 'live',
    'payment_processor'                 => 'stripe',
    'is_rebill'                         => 1,
    'amount'                            => 9.99,
    'buyer_ip'                          => '196.215.215.215',
    'buyer_first_name'                  => 'Ruggero',
    'buyer_last_name'                   => 'Sandri-Boriani',
    'buyer_email'                       => 'ruggero@sandri.com',
    'vendor_first_name'                 => 'Digital',
    'vendor_last_name'                  => 'Kickstart',
    'vendor_email'                      => 'support@digitalkickstart.com',
    'billing_address_1'                 => '',
    'billing_address_2'                 => '',
    'billing_city'                      => '',
    'billing_state'                     => '',
    'billing_zip'                       => '',
    'billing_country'                   => '',
    'shipping_address_1'                => '',
    'shipping_address_2'                => '',
    'shipping_city'                     => '',
    'shipping_state'                    => '',
    'shipping_zip'                      => '',
    'shipping_country'                  => '',
    'transaction_id'                    => 'PK-TN0LNO7XWR',
    'invoice_id'                        => 'PK-PZ1WK636WR',
    'tracking_id'                       => 216,
    'transaction_time'                  => 1469014598,
    'product_id'                        => 2354,
    'product_name'                      => 'SEO Snapshot - Main',
    'campaign_id'                       => 215,
    'campaign_name'                     => 'SEO Snapshot',
    'affiliate_first_name'              => 'Bob',
    'affiliate_last_name'               => 'Jones',
    'affiliate_email'                   => 'bob@jones.com',
    'affiliate_commission_amount'       => 4.99,
    'affiliate_commission_percent'      => 50,
    'ref_affiliate_first_name'          => null,
    'ref_affiliate_last_name'           => null,
    'ref_affiliate_email'               => null,
    'ref_affiliate_commission_amount'   => null,
    'ref_affiliate_commission_percent'  => null,
    'buyer_tax_number'                  => null,
    'buyer_tax_name'                    => null,
    'tax_transaction_id'                => null,
    'tax_amount'                        => null,
    'tax_percent'                       => null,
    'coupon_code'                       => '',
    'coupon_type'                       => '',
    'coupon_rate'                       => '',
    'custom_var1'                       => 123,
    'custom_var2'                       => 'email@user.com',
    'licenses'                          => ['HPLD-XSQW-KDW3-8HTD', 'AWDF-XADWR-HYTF-4T7B'],
    'hash'                              => '9f02b0208c3eb0710d57b05a61d9f411d023fca6'
    'verification_code'                 => 'e2288202ad23b877c3498a6db6214b5a417b75a4'
];

IPN Validation Function

<?php
function is_valid_ipn($data, $secret_key) {
        // Hash received
        $ipnHash = $data['hash'];

        // Unset encrypted keys
        unset($data['hash'], $data['verification_code']);

        // Trim and ommit empty/null values from the data
        $data = array_filter(array_map('trim', $data));

        // Alphabetically sort IPN parameters by their key. This ensures
        // the params are in the same order as when Paykickstart 
        // generated the verification code, in order to prevent 
        // hash key invalidation due to POST parameter order.
        ksort($data, SORT_STRING);

        // Implode all the values into a string, delimited by "|"
        // Generate the hash using the imploded string and secret key
        $hash = hash_hmac( 'sha1', implode("|", $data), $secret_key );
       
        return $hash == $ipnHash;
}

PayKickstart’s Instant Payment Notification (IPN) is a message service that automatically notifies vendors of events related to PayKickstart transactions. Vendors can use it to automate back-office and administrative functions, including automatically creating users on apps, providing customers with their login credentials via email etc.

ARGUMENTS

event

Stipulates the type of transaction event which has occurred. Each IPN that’s fired is fired based on a specific event, so it’s possible that a single transaction can fire multiple IPNs, particularly in the case of subscriptions. Please note that these IPN events may not be fired in any particular order. The event types are:

  • sales
    IPN is fired when any transaction is successful, even in the case of subscription rebills.
  • refund
    IPN is fired any time a transaction is refunded.
  • subscription-payment
    IPN is fired when any subscription transaction is created successfully.
  • subscription-created
    IPN is fired when a subscription has been created.
  • subscription-cancelled
    IPN is fired when a subscription has been cancelled.
  • subscription-completed
    IPN is fired when a subscription has completed. This occurs only with subscriptions which  have a limited number of payments and have successfully charged the final payment.
  • subscription-trial-start
    IPN is fired when a trial period has started
  • subscription-trial-end
    IPN is fired when a trial period has ended
  • subscription-payment-failed
    IPN is fired when a subscription payment fails
  • subscription-updated
    IPN is fired when a subscription is reactivated from inside the ui
  • subscription-changed
    IPN is fired when an existing subscription is upgraded / downgraded

mode

Indicates whether the transaction was executed in “live” mode or “test” mode. The parameter’s possible value are:

  • live
  • test

payment_processor

Indicates the payment gateway used to create the transaction. Supported payment gateways include:

  • stripe
  • paypaladaptive
  • paypalmarketplace
  • braintree
  • authnet

amount

The transaction amount

buyer_ip
buyer_first_name
buyer_last_name
buyer_email

The transaction’s buyer’s details

vendor_first_name
vendor_last_name
vendor_email

The transaction’s Paykickstart vendor’s details

billing_address_1
billing_address_2
billing_city
billing_state
billing_zip
billing_country

The transaction’s buyer’s billing details

shipping_address_1
shipping_address_2
shipping_city
shipping_state
shipping_zip
shipping_country

The transaction’s buyer’s shipping details

transaction_id

The unique Paykickstart transaction ID


invoice_id

The unique Paykickstart purchase ID


old_invoice_id

The original Paykickstart purchase ID of the old subscription (only included in the subscription-changed event)


tracking_id

The transaction’s Paykickstart affiliate’s tracking link id


transaction_time

The time when the transaction was generated, in UNIX timestamp format.


product_id
product_name

The transaction’s product details

campaign_id
campaign_name

The transaction’s campaign details

affiliate_first_name
affiliate_last_name
affiliate_email
affiliate_commission_amount
affiliate_commission_percent

The transaction’s Paykickstart affiliate’s details and the amount paid to the affiliate for this transaction. Both the commission value and percentage amounts are indicated.


ref_affiliate_first_name
ref_affiliate_last_name
ref_affiliate_email
ref_affiliate_commission_amount
ref_affiliate_commission_percent

The transaction’s Paykickstart 2nd tier affiliate’s details and the amount paid to that affiliate for this transaction. Both the commission value and percentage amounts are indicated.


update_billing_url

* Only available in the subscription-payment-failed IPN event. Returns the URL where the customer may update their payment details for the subscription in which their payment failed.


next_billing_date

* Only available in the sales IPN event, and only if applicable (i.e. not populated in the case of 1-time transactions). Returns the unix timestamp of when the subscription will next charge (in GMT0 timezone).


custom_{field}

Field names prefixed with “custom_” in the IPN POST are custom fields which you may set in the checkout page URL. For example, if your Paykickstart checkout page URL is https://app.paykickstart.com/checkout/123, you can add additional information to the URL in the form of GET variables like this:

https://app.paykickstart.com/checkout/123?var1=123&var2=email@user.com

Continuing with the example above, we’d pass these custom variables back to you in the IPN POST, like this:

custom_var1 = 123
custom_var2 = ’email@user.com’


licenses

Returns any licenses linked to the transaction, either as an array if more than 1 license, or a string if only 1 license.


verification_code

This is a hashed security key that can be used to validate that the IPN POST received is in fact valid / verified. You should generate a hash using the function provided (see IPN Validation Function on the left) and compare it against the hash within the POST. If they match, the IPN is verified. The secret key variable required by the IPN validation function is located in your campaign settings (see screenshot below).

pk_ipn_secret_key

Leave A Comment?