Subscription

This tutorial helps you to setup Brick subscription into your payment system.

Subscription request

We assume that you have collected one-time token and fingerprint on your backend side. You can then use this code to define subscription for your product. See subscription API for the format of parameters.

<?php
Paymentwall_Config::getInstance()->set(array(
    'private_key' => 'YOUR_PRIVATE_KEY'
));

$parameters = $_POST;
$subscriptionInfo = array(
    'token' => $_POST['brick_token'],
    'email' => $_POST['email'],
    'currency' => 'USD',
    'amount' => 10,
    'fingerprint' => $_POST['brick_fingerprint'],
    'plan' => 'product_123',
    'description' => 'Order #123',
    'period' => 'week',
    'period_duration' => 2
);

$subscription = new Paymentwall_Subscription();
$subscription->create($subscriptionInfo);
?>

// We are using Express framework in this sample

var Paymentwall = require('paymentwall');
Paymentwall.Configure(                                                        
    Paymentwall.Base.API_GOODS,
    'YOUR_PUBLIC_KEY',
    'YOUR_PRIVATE_KEY'
);

//custom parameters
var custom = {
    'plan': 'product_123', // your product id
    'YOUR_CUSTOM_PARAMETER_NAME': 'YOUR_CUSTOM_PARAMETER_VALUE'
};

var parameters = req.body;
var subscription = new Paymentwall.Subscription(
    0.5, //price
    'USD', //currency code
    'description', //description of the product
    req.body.email, // user's email
    req.body.brick_fingerprint, // fingerprint generated by Brick.js
    req.body.brick_token, //one-time token
    'week', // period
    2, // period_duration
    custom 
);

subscription.createSubscription(function(brick_response){
    // Handle response
});

Config.getInstance().setPublicKey("YOUR_PUBLIC_KEY");
Config.getInstance().setPrivateKey("YOUR_PRIVATE_KEY");

LinkedHashMap<String, String> subscriptionmap = new LinkedHashMap<String, String>();

subscriptionmap.put("token", request.getParameter("brick_token"));
subscriptionmap.put("email", request.getParameter("email"));
subscriptionmap.put("currency", "USD");
subscriptionmap.put("amount", "9.99");
subscriptionmap.put("description", "YOUR-DESCRIPTION");
subscriptionmap.put("fingerprint", request.getParameter("brick_fingerprint"));
subscriptionmap.put("plan", "YOUR-PRODUCT-ID");
subscriptionmap.put("period", "week");
subscriptionmap.put("period_duration", "1");

Subscription subscription = new Subscription();
subscription = (Subscription) subscription.create(subscriptionmap);

curl https://payments.terminal3.com/api/brick/subscription \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]" \
-d "token=[TOKEN]" \
-d "email=user@host.com" \
-d "history[registration_date]=1489655092"
-d "currency=USD" \
-d "amount=10" \
-d "fingerprint=[FINGERPRINT_BY_BRICK.JS]" \
-d "description=Order #123" \
-d "plan=product_123" \
-d "period=week" \
-d "period_duration=2"

Setup trial period

If you want to provide a trial period for your customers, you can add a trial product on the subscription.

<?php
Paymentwall_Config::getInstance()->set(array(
    'private_key' => 'YOUR_PRIVATE_KEY'
));

$parameters = $_POST;
$subscriptionInfo = array(
    'token' => $_POST['brick_token'],
    'email' => $_POST['email'],
    'currency' => 'USD',
    'amount' => 10,
    'fingerprint' => $_POST['brick_fingerprint'],
    'plan' => 'product_123',
    'description' => 'Order #123',
    'period' => 'week',
    'period_duration' => 2,
    'trial[amount]' => 1,
    'trial[currency]' => 'USD',
    'trial[period]' => 'month',
    'trial[period_duration]' => 1
);

$subscription = new Paymentwall_Subscription();
$subscription->create($subscriptionInfo);
?>

// We are using Express framework in this sample

var Paymentwall = require('paymentwall');
Paymentwall.Configure(                                                        
    Paymentwall.Base.API_GOODS,
    'YOUR_PUBLIC_KEY',
    'YOUR_PRIVATE_KEY'
);

//custom parameters
var custom = {
    'plan': 'product_123', // your product id
    'YOUR_CUSTOM_PARAMETER_NAME': 'YOUR_CUSTOM_PARAMETER_VALUE'
};

var trail = {
    amount: 0.5,
    currency: 'USD',
    period: 'day',
    period_duration: 3
}

var parameters = req.body;
var subscription = new Paymentwall.Subscription(
    0.5, //price
    'USD', //currency code
    'description', //description of the product
    req.body.email, // user's email
    req.body.brick_fingerprint, // fingerprint generated by Brick.js
    req.body.brick_token, //one-time token
    'week', // period
    2, // period_duration
    trail,
    custom 
);

subscription.createSubscription(function(brick_response){
    // Handle response
});

Config.getInstance().setPublicKey("YOUR_PUBLIC_KEY");
Config.getInstance().setPrivateKey("YOUR_PRIVATE_KEY");

LinkedHashMap<String, String> subscriptionmap = new LinkedHashMap<String, String>();

subscriptionmap.put("token", request.getParameter("brick_token"));
subscriptionmap.put("email", request.getParameter("email"));
subscriptionmap.put("currency", "USD");
subscriptionmap.put("amount", "9.99");
subscriptionmap.put("description", "YOUR-DESCRIPTION");
subscriptionmap.put("fingerprint", request.getParameter("brick_fingerprint"));
subscriptionmap.put("plan", "YOUR-PRODUCT-ID");
subscriptionmap.put("period", "week");
subscriptionmap.put("period_duration", "1");

subscriptionmap.put("trial[amount]", "0.5");
subscriptionmap.put("trial[currency]", "USD");
subscriptionmap.put("trial[period]", "day");
subscriptionmap.put("trial[period_duration]", "3");
Subscription subscription = new Subscription();
subscription = (Subscription) subscription.create(subscriptionmap);

curl https://payments.terminal3.com/api/brick/subscription \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]" \
-d "token=[TOKEN]" \
-d "email=user@host.com" \
-d "history[registration_date]=1489655092"
-d "currency=USD" \
-d "amount=10" \
-d "fingerprint=[FINGERPRINT_BY_BRICK.JS]" \
-d "description=Order #123" \
-d "plan=product_123" \
-d "period=week" \
-d "period_duration=2" \
-d "trail[amount]=0.5" \
-d "trail[currency]=USD" \
-d "trail[period]=day" \
-d "trail[period_duration]= 3"

Subscription response object

Once a subscription request is successfully performed, you will get a subscription response object which contains the subscription details. See subscription response attributes for more details.

Each subscription has several charge id which represents the payments in subscription histroy.

Terminal3 Payments instant payment notification, pingback, will be sent immediately once a subscription request is achieved. Your delivery should be performed according to the type of our pingback. You may also define your own parameter as additional parameters in subscription request which can be set as custom pingback parameters for transparent transmission in charge request.

Subscription Schedule

Once a user makes his first payment via subscription, we are authorized for recurring billing until his subscription expired.

We will automatically charge the user based on the subscription schedule. E.g. if you specify the product length as 1 month, we will charge the user every month. Next payment will happen on the same day of the next month. For example, if a payment happens on 30th of January, the next payment will be made in first days of March.

Every time a user is billed, we will send a new pingback.

Once the last charge happens Terminal3 Payments will send a pingback with type=13, which means the subscription is expired.

Subscription failure

If a user has insufficient funds or a payment fails for any other reason, Terminal3 Payments will make 2 reattempts (3 attempts in total) to charge the user. Payment Status API will report active status of the subscription and date_next will contain the date of the next attempt.

If all of the attempts fail, Terminal3 Payments will stop the subscription. Once the subscription stopped, it will no longer process an attempt to charge the user for the next scheduled payment.

For this event Terminal3 Payments will send a pingback with type=14, means subscription payment failed.

Subscription cancellation

You can also cancel the subscription by using scripts below or using our cancellation API.

<?php
$subscription = new Paymentwall_Subscription('SUBSCRIPTION_ID');
$subscription->cancel();

echo $subscription->isActive();
?>

var subscription = new Paymentwall.Subscription();
subscription.otherOperation(subscriptionid,'cancel',function(response){
    response.getFullResponse('JSON');
});

Subscription subscription = new Subscription("SUBSCRIPTION_ID");

subscription = (Subscription)(subscription.cancel());

return subscription.isActive();

Next step

That’s it! Your payment system now can handle the subscription payments. You will need to implement 3D secure as next step.

Questions?

Common questions are covered in the FAQ.
For integration and API questions, feel free to reach out Integration Team via integration@terminal3.com.
For business support, email us at sales@terminal3.com.
To contact sales, email sales@terminal3.com.