Click here to access Thank You page protection info

 

Instant Payment Notifications

There is Instant Payment Notification system within PayDotCom platform, which allows you to get calls on your 3rd party services.

Please, be aware that service is intended to be used by software developers. If you do not have enough knowledge in the field, please, you better get help of experienced programmers.

Key moments:

• data is sent via HTML FORM POST
• data is sent to a URL, you specify in settings
• data contains info relevant to payment or subscription
• sent information is encrypted
• for decryption secret key and initialization vector must be used
• secret key must be set in settings

Flow

1. Event occurred.
2. Data is encrypted with usage of secret key you set and an initialization vector.
3. Notification is sent to URL you specified via HTML FORM POST.
4. Your receiving application decrypts notification and processes data.
5. PayDotCom indicates notification as received via success response.

URL

To use this Instant Payment Notifications System you must create target application (that will receive, decrypt and process data) and set URL to which notification is sent. URL should use Transport Layer Security (TLS) or Secure Socket Layer (SSL). You can use ports 80 or 443. You are insisted to use TLS or SSL enabled. Using this service without it can cast towards your sales data to thieves. Any bank (or credit card) information is not used in IPNs, so we do not make you to use TLS or SSL to encrypt notifications.

Important:  Self-signed SSL certificates can not be used. Only valid certificates must be used.

Supported events

PayDotCom provides support for sending notification on next events in your account activity:

1. Sale - sale of product (including initial/trial sale)
2. Refund - refund of any transaction
3. Partial Refund - refund of any transaction with partial amount
4. Subscription regular payment - scheduled payments on subscription
5. Cancel Subscription - subscription is cancelled on any of reason
6. Reactivate Subscription - subscription is reactivated

Notification Format

Notifications are created in the JSON format. Primary structure:

{

"notification": "en_notification",

"iv": "security_cypher"

}

 

en_notification - encrypted notification

security_cypher - initialization vector

Encryption

• CBC-AES-256 used encryption algorithm
• secret key, is up to 16 characters
• initialization vector is used in parallel with your PayDotCom secret key

Parameters

This section describes all of the parameters used in a notification.

When a notification is sent, it includes all parameters. If a parameter contains no value, the instant notification string contains the parameter tag without a value. This is why the number of characters for some parameters includes zero, as these parameters may not contain a value.

 

Header Parameters 

Parameter	Description	Characters / Format	Recipient
transactionTime	Time of transaction in RFC-3339 format	25	Vendor
transactionIdentifier	PayDotCom payment identifier	8-21	Vendor
transactionType	The type of transaction.	4-15 – See Transaction Types	Vendor
vendorID	The vendor ID in PayDotCom	5-10	All
affiliateID	The affiliate ID in PayDotCom	5-10	All
role	Your role in the transaction	6-9 – VENDOR, AFFILIATE	All
receivedAmount	Total you received for the transaction in USD	Numeric with 2 decimal precision	Vendor
paymentService	Payment method used by the customer.	3-4 – See Payment Methods	Vendor
paidAmount	Total the customer paid	Numeric with 2 decimal precision	Vendor
currency	Currency the user paid in	3	All
orderLanguage	Language used on the order form	2	All

 

Product Parameters 

Parameter	Description	Characters / Format	Recipient
productID	Product ID in PayDotCom	1-25	All
productName	Product title	0-255	All
recurring	Whether the product was subscription-based	4-5 – true or false	All
productPrice	Product price on PayDotCom	Numeric with 2 decimal precision	All

 

Customer Parameters

Parameter	Description	Characters	Recipient
firstName	Customer's first name	0-255	All
lastName	Customer's last name	0-255	All
contactEmail	Customer's email address	0-255	All

 

Customer Billing Parameters

Parameter	Description	Characters	Recipient
firstName	Customer's first name	0-255	All
lastName	Customer's last name	0-255	All
fullName	Customer's first and last name	0-255	All
phoneNumber	Customer's phone number	0-255	All
email	Customer's email address	0-255	All
state	Customer's state	0-255	All
postalCode	Customer's postal code or zip code	0-255	All
country	Customer's country	0-255	All

 

Affiliate Parameters

Parameter	Description	Characters / Format	Recipient
firstName	The affiliate first name	String	All
lastName	The affiliate last name	String	All
publicId	The affiliate ID in PayDotCom	String	All

 

Vendor Parameters

Parameter	Description	Characters / Format	Recipient
firstName	The vendor first name	String	All
lastName	The vendor last name	String	All
publicId	The vendor ID in PayDotCom	String	All

 

Technical Parameters 

Parameter	Description	Format	Recipient
version	The version of the instant notification.	Double Numeric	All
attemptCount	The number of times PayDotCom tried to send this notification before receiving a success or failing with too many attempts	Integer	All

 

Transaction Types

There are a number of values you can receive in the transactionType parameter. These values are listed below with a brief description of their purpose.

Type	Description
SALE	The purchase of a standard product or the initial purchase of recurring billing product.
BILL	A rebill for a recurring billing product.
RFND	The refunding of a standard or recurring billing product. Recurring billing products that are refunded also result in a "CANCEL-REBILL" transaction.
CANCEL-REBILL	The cancellation of a recurring billing product. Recurring billing products that are canceled do not result in any other action.
UNCANCEL-REBILL	Reversing the cancellation of a recurring billing product.
TEST	A test transaction triggered during configuration.

 

Payment Methods

Payment Method Parameter	Payment Method
PYPL	Paypal
STRP	Credit Card

 

Notification Example

This is a sample of the unencrypted JSON notification showing the structure of the key-value pairs for Instant Notification.

{

techInfo: {

  version: 1.0,

  attemptCount: 1

},

transactionInfo: {

  transactionTime: '2017-05-24T12:28:43+03:00',

  transactionIdentifier: '********',

  transactionType: 'SALE',

  paymentService: 'PYPL',

  vendorID: '********',

  affiliateID: '********',

  receivedAmount: 0,

  paidAmount: 0,

  role: 'Vendor',

  currency: 'USD',

  orderLanguage: 'EN'

},

products_info: [

  {

    productID: '***',

    productName: 'Title',

    recurring: true,

    productPrice: '10.0'

  }

],

customerInfo: {

  contactInfo: {

    contactEmail: '[email protected]',

    firstName: 'Firstname',

    lastName: 'Lastname'

  },

  billingInfo: {

    firstName: 'Test',

    lastName: 'User',

    fullName: 'Test User',

    phoneNumber: '+1234567890',

    email: '[email protected]',

    address: {

      state: 'NY',

      postalCode: '54321',

      country: 'US'

    }

  }

},

affiliateInfo: {

  firstName: 'Firstname',

  lastName: 'Lastname',

  publicID: '********'

},

vendorInfo: {

firstName: 'Firstname',

  lastName: 'Lastname',

  publicID: '********'

}

}

Implementation

After gaining a sound understanding of the previous section of this document, you can request access to the Instant Notification feature.

Once you have configured one URL for Instant Notifications, you can add another. By default, you can add 3 URL per product.

Requesting Access to Instant Notifications

The Instant Notification feature is not automatically enabled. To request access to the Instant Notification you need do following steps:

 

For any sales

1. Log in to your PayDotCom account.
2. Click the icon with your image (on the left on site) and you’ll see context menu.
3. Click the My Account in context menu.
4. On a page, find chapter Instant Notification, fill fields Secret Key and IPN Notification URL.
5. After saving Secret Key you also can test IPN Notification URL.
6. After you filled fields click Save.

For product

1. Log in to your PayDotCom account.
2. In menu on the left Click Vendor.
3. In the opened menu Click Dashboard.
4. On the opened page find the product which you wish to add Instant Notification.
5. Click on Product Name.
6. In opened menu click IPN Url (page opened in new tab).
7. Select IPN Compatibility Mode.
8. After that fill fields Secret Key and IPN Notification URL.
9. Click Update IPN Settings.

Testing Connectivity and Processing

Before you can enable Instant Notifications, you must test the connectivity and successful processing of the URL parameters between PayDotCom and your server. To perform this test:

 

1. Log in to your PayDotCom account.
2. Click the icon with your image (on the left on site) and you’ll see context menu.
3. Click the My Account in context menu.
4. On a page, find chapter Instant Notification, fill field Secret Key. Your secret key can be up to 16 characters long, and must be entered in all caps.
5. Click Save.
6. After saving, fill field IPN Notification URL.
7. Click TEST IPN. (It’ll be sent test IPN call)
8. Review the response in the popup window to verify that the test was successful.

If the test was not successful, remove the URL from the Instant Notification field and troubleshoot possible problems with connectivity or your application.

NOTE – You should not populate the Instant Notification field unless you can conduct a successful test. Doing so may result in your access to the feature being disabled.

Enabling Instant Notifications

Once you have been granted access to the feature and conducted a successful test, you can enable Instant Notifications to begin receiving them. To enable Instant Notifications:

1. Log in to your PayDotCom account.
2. In menu on the left Click Vendor.
3. In the opened menu Click Dashboard.
4. On the opened page find the product which you wish to add Instant Notification.
5. Click on Product Name.
6. In opened menu click IPN Url (page opened in new tab).
7. Select IPN Compatibility Mode.
8. After that fill fields Secret Key and IPN Notification URL. Your secret key can be up to 16 characters long, and must be entered in all caps.
9. Click Update IPN Settings.

Once the setup is complete, the Instant Notification transmissions will begin immediately.

Disabling Instant Notifications

You can disable the feature to prevent notifications from being sent by removing your URL. You can re-enable the feature later.

1. Log in to your PayDotCom account.
2. In menu on the left Click Vendor.
3. In the opened menu Click Dashboard.
4. On the opened page find the product which you wish to remove Instant Notification.
5. Click on Product Name.
6. In opened menu click IPN Url (page opened in new tab).
7. In field Select IPN Compatibility Mode select Select mode...
8. Click Update IPN Settings.

Response Processing

When we send an instant notification, we monitor the response code from your URL. If the response code is in the 200 range, the notification delivery is considered successful.

If the response code is not in the 200 range, we send you system message about this error. On page My Account in chapter Instant Notification you have additional option: Retry option. This option give: attempt to resend the notification every 15 minutes 3 times. After 3 times failed attempts we send you system message about this error. Once you diagnose the cause of the failures, you can re-enable your URL. Send IPN call again and resume receiving instant notifications.

Code Samples

The data sent to you by the Instant Notification service is in the form of HTML FORM POST URL Parameters. Programs written within your application architecture must process these pairs. Programs for order management, database activity, and other services may be written but are outside the scope of this guide.

The following code samples cover decrypting the notification.

NOTE – The following code samples must be nested in a program. In addition, these samples will fail if your character set includes German, Greek, Eastern European, or Asian characters. You must perform your own encoding before decrypting instant notifications. 

Ruby

The following code sample uses Ruby to decrypt the notification.

 

require "base64" require "digest/sha1" require "json" require "openssl" # Decode the IPN post into a JSON object. # The message param is the raw HTTP POST # body of the notification def decrypt_clickbank_notification(message) parsed = JSON.parse(message); aes = OpenSSL::Cipher::Cipher.new("AES-256-CBC") aes.iv = Base64.decode64(parsed["iv"]) aes.decrypt aes.key = Digest::SHA1.hexdigest("YOUR SECRET KEY").slice(0, 32) aes.update(Base64.decode64(parsed["notification"])) + aes.final

 

 

PHP

The following code sample uses PHP to decrypt the notification.

 

<?php $input = file_get_contents('php://input'); $json = @json_decode($input, true); $secret = 'YOUR SECRET KEY'; $secret = substr(sha1($secret), 0, 32); $notification = base64_decode($json['notification']); $iv = base64_decode($json['iv']); $decoded = openssl_decrypt( $notification, 'AES-256-CBC', $secret, OPENSSL_RAW_DATA, $iv ); $data = json_decode($decoded, true); echo '<pre>'; print_r($data);" echo '</pre>';

 

NODE.JS

The following code sample uses NODE.JS

 

const server = require('http'); const crypto = require('crypto'); const algorithm = 'aes-256-cbc' const password_hash = crypto.createHash('sha1').update('Secret Key', 'utf-8').digest('hex').substr(0, 32); server.createServer(function (req, res) { if (req.method === "POST") { console.log('POST'); var buffer = ""; req.on("data", function (chunk) { buffer += chunk; }); req.on("end", function(){ const body = JSON.parse(buffer); const notification = body.notification; const iv = body.iv; const decodedData = decrypt(notification, iv); process_notification(decodedData); }); } }).listen(8080, "0.0.0.0"); var decrypt = (data, iv) => { var binaryIV = new Buffer( iv, "base64" ); var decipher = crypto.createDecipheriv( algorithm, password_hash, binaryIV ); decipher.setAutoPadding(false); var decryptedData = ( decipher.update( data, "base64", "utf8" ) + decipher.final( "utf8" ) ); return decryptedData; } var process_notification = (data) => { // process string data }