Knowledgebase
JVZIPN
Posted by John Siefer on 16 May 2012 04:50 PM

Overview

**This is an advanced topic.  This is only recommended for vendors with advanced programming knowledge or those that have the assistance of a programmer.

JVZIPN offers an integration solution for membership sites and other products that require information about Payment Notifications.

JVZIPN will send data via HTML FORM POST to a URL you specify, which will be the script using the information.  The information will POST for any of the following reasons:

  • Sales
  • Refunds
  • Rebills
  • Rebill Cancellations
  • Chargebacks
  • Tests

Whenever one of these actions is triggered in the JVZoo system, JVZIPN creates a notification.  That form data is then sent to your URL as a POST.  Your script will then analyze that data and use it in the way you program it to.  The cverify field is used to ensure the other fields contain valid entries and can be used to check that the information is coming from JVZoo.

 

What You Need to Know

In order to use the JVZIPN, there is some basic knowledge you (or your programmer) will need to know:

  1. How to read POSTed information in a script
  2. What post parameters are and how to use them
  3. How to use a Secret Key in a Cipher
  4. What Response Code Monitoring does

If you are unclear on any of these concepts, it is advised that you hire an experienced programmer or don’t attempt to use the JVZIPN system at this time.

Post Parameters:

These are parameters currently used in JVZIPN:

Parameter

Description

Detail

ccustname

customer name

1-510 Characters

ccuststate

customer state

0-2 Characters

ccustcc

customer country code

0-2 Characters

ccustemail

customer email

1-255 Characters

cproditem

JVZoo product number

1-5 Characters

cprodtitle

title of product at time of purchase

0-255 Characters

cprodtype

type of product on transaction (STANDARD, and RECURRING)

8-11 Characters

ctransaction *

action taken

4-15 Characters

ctransaffiliate

affiliate on transaction

0-10 Characters

ctransamount

amount paid to party receiving notification (in pennies (1000 = $10.00))

3-10 Characters

ctranspaymentmethod

method of payment by customer

0-4 Characters

ctransvendor

vendor on transaction

5-10 Characters

ctransreceipt

JVZoo Payment Id

16-22 Characters

cupsellreceipt ** 2

Parent receipt number for upsell transaction

8-13 Characters

caffitid

affiliate tracking id

0 – 24 Characters

cvendthru

extra information passed to order form with duplicated information removed

0-1024 Characters

cverify **

the “cverify” parameter is used to verify the validity of the previous fields

8 Characters

ctranstime **

the Epoch time the transaction occurred (not included in cverify)

10 Characters

 

* See “Transaction Types”
** See “Cipher”
2 Present when a parent receipt exists for the transaction

Transaction Types

These are the types of transactions (found in the “ctransaction” field of the IPN):

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” action.

CGBK

A chargeback for a standard or recurring product.

INSF

An eCheck chargeback for a standard or recurring product.

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.

Payment Methods

These are the values you can receive in the ctranspaymentmethod field:

‚óŹ        PYPL

 

Response Code Monitoring (Retry Logic)

JVZIPN will expect a response code from your script of 200.  If it receives anything other than a code of 200, the program will resend the data once an hour, for 72 hours, until a code of 200 is returned.  .

Cipher (Preventing Fraud)

A cipher is used to determine that the information being sent is from a trusted source.  Your script will contain a secret key that will also be the seed for the data encryption JVZIPN uses to send the information to your script.  If this key is not the same on both ends, the encryption will not be able to be read by your script.

Implementation

After gaining a sound understanding of the previous section of this document, we recommend that you test the feature before implementing. After completing a successful test, you can set up your account for the Instant Notification service.

Account Setup

Now that you have been granted access to the feature and have conducted a successful test, it’s time to complete the account setup of the Instant Notification service. Setting up the service is straightforward and involves the following steps.

  1. Log into your account
  2. Click the My Account tab
  3. Click the Edit Account button (top right)
  4. Enter your Secret Key
  5. Click save
  6. Click the Sellers tab
  7. Click your product in the sub nav
  8. Enter an Instant Notification URL in the JVZIPN URL field (ports 80 or 443 – SSL Recommended)
  9. Click Save Changes

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

Disabling

If you no longer wish to use JVZIPN, simply remove the forwarding URL from your listing.

FAQ

Q: Is it possible for the Instant Notification service to deliver more than one POST on a single receipt?

A: Yes. There are many scenarios where this is true. For instance, you will receive multiple POSTs for a single transaction if a refund is given and then reversed. This would result in delivery of a RFND action POST and then a SALE action post. The first action is a result of the original sale being refunded. The second action is a result of the sale being reinstated.

Q: Will I always receive all the Parameters or only when they contain values?

A: You will always receive all the parameters. When a parameter contains no value, the Instant Notification string will contain the parameter tag without a value.

Q: Why do some of the Parameters have a 0 in the number of characters to expect?

A: These Parameters may not contain any value during the post, which is why they are listed with the possibility for 0 characters.

Q: Am I required to use Cipher with JVZIPN?

A: It is required. You must add a secret key to your account to enable Instant Notifications.

Q: Are the code samples provided by JVZoo fully functional and ready to go?

A: No. The code sample you see is only a snippet of code to be used in a larger program or script.

Q: Will JVZIPN work with a self-signed SSL certificate?

A: No. A valid certificate is required.

Code Sample

PHP

Cipher (Validation Processing Code)

This PHP snippet will create the cverify value and verify if it is correct using the plain text values in the HTTP POST and your secret key (e.g. not URL-encoded).

Response Types:
1 = Pass
0 = Fail

Code Sample

<?php

 

function jvzipnVerification() {
    $secretKey = "MyJVZIPNSecretKey";
    $pop = "";
    $ipnFields = array();
    foreach ($_POST AS $key => $value) {
        if ($key == "cverify") {
            continue;
        }
        $ipnFields[] = $key;
    }
    sort($ipnFields);
    foreach ($ipnFields as $field) {
        // if Magic Quotes are enabled $_POST[$field] will need to be
        // un-escaped before being appended to $pop
        $pop = $pop . $_POST[$field] . "|";
    }
    $pop = $pop . $secretKey;
    $calcedVerify = sha1(mb_convert_encoding($pop, "UTF-8"));
    $calcedVerify = strtoupper(substr($calcedVerify,0,8));
    return $calcedVerify == $_POST["cverify"];
}

?>

 

(73 votes)
This article was helpful
This article was not helpful

Comments (0)
Post a new comment
 
 
Full Name:
Email:
Comments:
Help Desk Software by Kayako case