New Purchase

PayKickstart’s New Purchase API call is a highly flexible system designed to allow you as the vendor complete flexibility in terms of creating and managing new purchases. Using the API, you’re able to override your products’ default price settings, or even create a new charge without needing a client’s credit card information (reference transaction).

CUSTOMER PAYMENT DATA TOKENISATION

The Paykickstart API supports accepting payment processor tokens in order to effect payment as opposed to raw card data. It is therefore a TWO-PART system. The first part involves creating tokens directly from your checkout page using javascript provided by your payment processor, and the second part involves sending those tokens to the Paykickstart API endpoint.

FIRST PART:

We have created an example page which you can access to view the javascript required for each of your processors in each of your campaigns, as well as a copy-and-paste javascript you can use on your checkout pages to simplify the process.

In order to access this, please login to your Paykickstart vendor account, then go to this URL: https://app.paykickstart.com/test-code-v2/pci. The page which loads will list all your current campaigns and their associated processor integrations:

Click “go” next to the campaign you are integrating with using the API. On the following page, you’ll find tabs at the top for your supported payment types (credit card, SEPA, ACH etc.) and an “all” option. Clicking on any of those tabs will provide you with a sample form and javascript, as well as the done for you, copy-and-paste javascript sample at the top of the page.

The done-for-you PK tokenize javascript MUST BE PLACED BELOW THE PURCHASE FORM ELEMENT in the DOM structure. It accepts the following GET variables:

ccNum

The form field element ID which is responsible for capturing the customer’s credit card number.

ccExpireMonth

The form field element ID which is responsible for capturing the customer’s credit card’s expiry month_column]


ccExpireYear

The form field element ID which is responsible for capturing the customer’s credit card’s expiry year

ccCSV

The form field element ID which is responsible for capturing the customer’s credit card’s CSV number

ccBtn

The form field element ID which is responsible for submitting the form with credit card details

ppBtn

The form field element ID where the PayPal button will be rendered into.

form

The form’s DOM element ID

ccExpireYear

The form field element ID which is responsible for capturing the customer’s credit card’s expiry year

wt_account_holder_name

The form field element ID which is responsible for capturing the customer’s account holder name

sepa_email

The form field element ID which is responsible for capturing the customer’s email address for SEPA verification

iban_number

The form field element ID which is responsible for capturing the customer’s IBAN account number

sepaBtn

The form button ID which is responsible for generating the customer’s SEPA token

route_number

The form field element ID which is responsible for capturing the customer’s ACH account route number

account_number

The form field element ID which is responsible for capturing the customer’s ACH account number

achBtn

The form button ID which is responsible for capturing the customer’s credit card’s expiry year

ccExpireYear

The form field element ID which is responsible for generating the customer’s ACH token

billing_address_1

The form field element ID which is responsible for capturing the customer’s billing address line 1 (used when creating the payment profile / token, if supplied)

billing_address_2

The form field element ID which is responsible for capturing the customer’s billing address line 1 (used when creating the payment profile / token, if supplied)

billing_city

The form field element ID which is responsible for capturing the customer’s billing address city (used when creating the payment profile / token, if supplied)

billing_state

The form field element ID which is responsible for capturing the customer’s billing address state (used when creating the payment profile / token, if supplied)

billing_zip

The form field element ID which is responsible for capturing the customer’s billing address zip code (used when creating the payment profile / token, if supplied)

billing_country

The form field element ID which is responsible for capturing the customer’s billing address country (used when creating the payment profile / token, if supplied)

You may choose to NOT use that done for you PK tokenisation script if your form is a bit more complex, in which case the example javascript provided may be copied to your own form and modified as required:

You can also fill in the form field provided on the page and click “click me” to see an example output of the working javascript:

Using the generated token, you can submit an API call (see below) to process the transaction.

SECOND PART:

Example Request

<?php
//Set up API path and method
$base_url = "https://app.paykickstart.com/api/";
$route = "purchase";
$url = $base_url . $route;
$post = true;

//Create request data string
$data = http_build_query([
    "auth_token" => "DLFJKGHW9834",
    "product" => 80,
    "plan" => 137,
    "first_name" => "Jack",
    "last_name" => "Sparrow",
    "email" => "jack@sparrow.com",
    "stripeToken" => "tok_1DrPnbGHbWjVjDgKnht3VpQW",
    "is_recurring" => 1,
    "price" => 12,
    "recurring_freq" => 1,
    "recurring_freq_type" => "day",
    "cycles" => 3,
    "ccNum" => 1985,
    "ccExpireYear" => 2020,
    "ccExpireMonth" => 12
]);

//Execute cURL request
$ch = curl_init();
if ($post) {
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
} else {
    $url = $url . "?" . $data;
}
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_URL, $url);
$output = curl_exec($ch);
curl_close($ch);

//Output Response
echo json_decode($output);

Example Response

{
  "data": {
    "event": "sales",
    "mode": "live",
    "payment_processor": "stripe",
    "amount": "9.00",
    "buyer_ip": "127.0.0.1",
    "buyer_first_name": "Micky",
    "buyer_last_name": "Mouse",
    "buyer_email": "mickeymouse@gmail.com",
    "vendor_first_name": "Digital",
    "vendor_last_name": "Kickstart",
    "vendor_email": "test@vendor.com",
    "transaction_id": "PK-TORW2N8NE5",
    "invoice_id": "PK-PN7E5R9NW5",
    "tracking_id": "",
    "transaction_time": 1485940001,
    "product_id": 2425,
    "product_name": "TEst product",
    "campgaign_id": 258,
    "campaign_name": "Test Demo Campaign",
    "affiliate_first_name": "Jack",
    "affiliate_last_name": "Sparrow",
    "affiliate_email": "",
    "affiliate_commission_amount": "",
    "affiliate_commission_percent": "",
    "ref_affiliate_first_name": "",
    "ref_affiliate_last_name": "",
    "ref_affiliate_email": "",
    "ref_affiliate_commission_amount": "",
    "ref_affiliate_commission_percent": "",
    "licenses": "",
    "verification_code": "d0822d01a254c2f394265dae22de8aecdaed08e5"
  },
  "url": null,
  "type": 1,
  "plan": 2425
}

In this step, the token generated from the first step is submitted along with your new purchase request data / instructions. Below are the arguments the API call accepts:

ARGUMENTS

auth_token

The Paykickstart vendor’s API Key. This field is required.


product

The campaign’s id. This field is required.

plan

The product’s id. This field is required.

affiliate_id

The paykickstart affiliate id for the affiliate which should be credited (and/or receive commission) for the purchase. The commission settings from the campaign / product / affiliate overrides will be used to calculate the commission owed.


first_name

The buyer’s first name. This field is required.


last_name

The buyer’s last name. This field is required.


email

The buyer’s email address. This field is required.


ref_purchase

Instead of providing the buyer’s PayPal or credit card information via token to create the purchase, you can pass the invoice_id you receive via the IPN post as the ref_purchase. This will cause the system to use the payment profile already stored in Paykickstart and associated to that original purchase to create the new purchase. This field is not required, provided that a token is submitted instead.

test_mode

Create this purchase using Paykickstart’s native “test mode” ability. This field is not required.

price

Override the product’s price amount for this purchase. If this field is not set, the price from the product’s settings is used.

split_selected

Override to charge the product as a “split pay”. This field is not required unless you are setting total_installments and price_per_installment.

total_installments

The number of split pay installments to be set. This field is only required when split_selected is set

price_per_installment

The price per split pay installment. This field is required when split_pay_selected is set, and must also be LESS that the product’s main price.

is_recurring

Enable a subscription-based product purchase. This field is not required unless you are setting up the purchase to be a subscription (see fields below)

recurring_freq

The number of recurring_freq_type E.g. recurring_frequency of 2 and a recurring_freq_type of months, means the subscription will charge every 2 months. This field is required when is_recurring is set.

recurring_freq_type

The recurring period for the recurring payment. Valid values are:

  • day
  • month
  • year

This field is required when is_recurring is set.


cycles

The number of payments for your subscription. Set as null for an infinite subscription. This field is required when is_recurring is set.

has_trial

Enable trial period for the purchase. Please note this is only currently possible for recurring subscription products. This field is not required unless you which to create a trial period for your product.

trial_amount

The initial amount to charge for the trial. Amount may be set to 0 for free trial. This field is not required unless you have has_trial enabled.

trial_days

The number of days before the subscription transactions begin. For example, if you want to set a 14 day free trial, make sure the product is set to recurring in its settings or via the API, then set trial_amount to 0 and trial_days to 14. This field is not required unless you have has_trial enabled.

capture_billing_address

Option to toggle whether or not you want to capture the buyer’s billing address. This field is not required.

    • billing_address_1
    • billing_address_2
    • billing_city
    • billing_state
    • billing_zip
    • billing_country
Billing address detail fields. All fields are required when capture_billing_address is set

capture_shipping_address

Option to toggle whether or not you want to capture the buyer’s shipping address. This field is not required.

      • shipping_address_1
      • shipping_address_2
      • shipping_city
      • shipping_state
      • shipping_zip
      • shipping_country
Shipping address detail fields. All fields are required when capture_shipping_address is set

tos-read

Boolean (accepts 0 or 1 as values). Indicates that the user has accepted your terms of service. Required if Terms of Service option is enabled in the product’s settings.

ccNum

The last 4 digits of the customer’s credit card number.

ccExpireYear

The 4-digit expiry year of the customer’s credit card.

ccExpireMonth

The 2-digit expiry month of the customer’s credit card.

custom_field[‘<FIELDNAME>’]

Pass as many custom fields you like through to the purchase api. Replace <FIELDNAME> with the field name of your choice.  This field is not required.

Below outlines the token fields required in the API call depending on your payment processor:

Stripe Credit Card:

stripeToken

The token generated by Stripe JS on your checkout page when accepting Credit Card data.

Stripe SEPA:

stripeSourceId

The source generated by Stripe JS on your checkout page when accepting bank details.

sepa

The last 4 digits of the IBAN number

wt-type

This should be set to: sepa

Stripe ACH:

stripeSourceId

The source generated by Stripe JS on your checkout page when accepting bank details.

route_number

The customer’s bank’s route number

account_number

The last 4 digits of the customer’s account number number

stripeBAToken

The Stripe bank token ID returned from Stripe JS

wt-type

This should be set to: ach

Braintree Credit Card:

pay_method_nonce

The Baintree token created by BraintreeJS when accepting Credit Card  purchases using Braintree.

Authorize.net:

dataDescriptor

Should be set to:
COMMON.ACCEPT.INAPP.PAYMENT

dataValue

The token ID returned from Authorize.net AcceptJS

Easy Pay Direct:

epdSaleToken

The sale token ID returned from Easy Pay Direct

epdCustomerToken

The customer profile token ID returned from Easy Pay Direct

PayPal / Braintree PayPal:

paypal_ba_id

The authorization token created returned from PayPal / BT PayPal.