Integrate Subscriptions

FasterPay allows you to create subscriptions for your customers and charge them on a recurring basis. This includes features such as monthly billing, free trials, and canceling subscriptions via API.


Prerequisites

To integrate Subscriptions you will need your API keys which you can find in your FasterPay Business account. If you don’t have a FasterPay Business account yet, you can sign up for one.

You can start testing the API and follow the steps below using the Test Mode and Go Live after.


How do Subscriptions work?

  1. The customer clicks on the Pay Button on your website and is redirected to the FasterPay checkout page.
  2. The customer makes a payment and sets up a subscription with your website’s services. FasterPay then sends a Pingback to your servers.
  3. The customer is then redirected to your Thank You page.
  4. FasterPay will then charge the customer on a pre-agreed recurring basis. For each scheduled payment, your servers will receive a Pingback.
FasterPay subscription integration

How to integrate Subscriptions

To integrate Subscriptions into your FasterPay Business account follow the steps below:

Step 1: Redirect your customer to the Checkout Page

Once your customer wants to pay, redirect them to FasterPay Checkout Page using the code below:

<?php
include('lib/autoload.php');

$gateway = new FasterPay\Gateway(array(
  'publicKey' 	=> '<your public key>',
  'privateKey'	=> '<your private key>',
));
$form = $gateway->paymentForm()->buildForm(
 array(
  'description' => 'Test order',
  'amount' => '10',
  'currency' => 'USD',
  'merchant_order_id' => 'xxxxxx',
  'success_url' => 'https://yourcompanywebsite.com/success',
  'recurring_name' => 'recurring1',
  'recurring_sku_id' => 'recurring1',
  'recurring_period' => '6m',
  'recurring_trial_amount' => '30',
  'recurring_trial_period' => '1m'
 )
);
echo $form;
?>
from fasterpay.gateway import Gateway
if __name__ == "__main__":
 gateway = Gateway("<your private key>", "<your public key>")
 payload = {
  "description": "Golden Ticket",
  "amount": "10",
  "currency": "EUR",
  "merchant_order_id": "xxxxx",
  "success_url": "https://yourcompanywebsite.com/success",
  "recurring_name": "Test FP Recurring",
  "recurring_sku_id": "fp_test_recurring",
  "recurring_period": "10d",
  "recurring_trial_amount": "1",
  "recurring_trial_period": "3d",
  "recurring_duration": 0
 }

 paymentForm = gateway.payment_form().build_form(payload)

 print paymentForm
curl https://pay.fasterpay.com/payment/form \
-d "api_key: [YOUR_PUBLIC_KEY]" \
-d "merchant_order_id=w2183261236" \
-d "amount=9.99" \
-d "currency=USD" \
-d "email=user@host.com" \
-d "description=Golden Ticket" \
-d "recurring_name=Golden Ticket Subscriptions" \
-d "recurring_sku_id=SKU ID / Product ID" \
-d "recurring_period=3m" \
-d "hash=<hash generated using the combination of post params and merchant private key>"

You can find more information on the API parameters in the Subscription API.


Step 2: Process the Pingback

After the customer makes a payment, FasterPay will send a Pingback to your servers notifying you about the payment.

You can use the code below to validate the Pingback, track the payment in your server and deliver the product:

<?php
include('lib/autoload.php');

$gateway = new Fasterpay\Gateway(array(
  'publicKey'     => '<your public key>',
  'privateKey'    => '<your private key>',
));

$pingbackData = json_decode(file_get_contents('php://input'), true);
if(!empty($pingbackData)){
  if($gateway->pingback()->validate(
    array("apiKey" => $_SERVER["HTTP_X_APIKEY"]))
  ){
    #TODO: Write your code to deliver contents to the End-User.
    echo "OK"; exit();
  }
}
echo "NOK";
?>
from flask import request
from fasterpay.gateway import FP_Gateway
gateway = Gateway("<your private key>", "<your public key>")
if gateway.pingback().validate({"apiKey": request.headers.get("X-ApiKey")}) is True:
  print "OK"
else:
  print "NOK"
curl --header "Content-Type: application/json" \
  --request POST \
  --data '{ \
    "event":"payment", \
    "payment_order":{ \
      "id":273281973, \
      "merchant_order_id":"w2981398127", \
      "payment_system":1, \
      "status":"successful", \
      "paid_amount":46.049999999999997, \
      "paid_currency":"EUR", \
      "merchant_net_revenue":42.227200000000003, \
      "merchant_rolling_reserve":2.3025000000000002, \
      "fees":1.5203, \
      "date":{ \
        "date":"2018-11-30 23:59:10.000000", \
        "timezone_type":3, \
        "timezone":"UTC" \
      } \
    }, \
    "user":{ \
      "firstname":"John", \
      "lastname":"Doe", \
      "username":"John-Doe@my.passport.io", \
      "country":"US", \
      "email":"johndoe@example.com" \
    }, \
    "with_risk_check":false, \
  }'
 https://your-pingback-url.com/pingback.php

FasterPay expects the following response:

Response Status: 200

Response Body: ok

In case a different response is received, FasterPay will resend Pingbacks every 30 minutes for up to 10 times.

You can also accept a range of Pingback types, such as refunds and chargebacks.

More about Pingbacks.


Step 3: Show your Thank You page.

Once the user makes a payment, they will be redirected to the success_url page that you specify during step.1. You can show your “Thank You” message on this screen.


Step 4: Process subscription Pingbacks.

FasterPay will send Pingbacks for the following events:

Recurring payment

When a customer is automatically charged for the subscription, FasterPay will send the pingback below:

{
 "event": "payment",
 "payment_order": {
   "id": 1005002001,
   "merchant_order_id": "w146138485",
   "status": "successful",
   "paid_amount": 5,
   "paid_currency": "USD",
   "merchant_net_revenue": 4.23,
   "merchant_rolling_reserve": 0.25,
   "fees": 0.52,
   "date": {
     "date": "2018-04-25 12:15:07.000000",
     "timezone_type": 3,
     "timezone": "UTC"
   }
 },
 "user": {
   "firstname": "John",
   "lastname": "Smith",
   "username": "john-smith@my.passport.io",
   "country": "TR",
   "email": "john.smith@email.com"
 },
 "subscription": {
   "id": 100345508,
   "u_email": "john.smith@email.com",
   "recurring_id": 1005002001,
   "status": "Trial",
   "cancel_delay": 0,
   "currency_code": "USD",
   "trial": 1,
   "trial_price": "5.00",
   "trial_period_length": 3,
   "trial_period_type": "day",
   "counter": 1,
   "limit": 0,
   "failures": 0,
   "period_length": 10,
   "period_type": "day",
   "billing_type": 1,
   "price": "105.00",
   "date_active": 0,
   "date_start": 1533704765,
   "date_next": 1533963965,
   "date_end": 1565067965,
   "date_paid": 1533704765,
   "date_expired": 0,
   "date_cancelled": 0,
   "date_stopped": 0,
   "created_at": 1533704765,
   "package_version_id": 213,
   "change_request": null,
   "package": {
     "id": 0,
     "sku_id": "your_product_sku_id",
     "name": "your product name",
     "currency_code": "USD",
     "period_length": 10,
     "period_type": "day",
     "recurring_limit": 0,
     "trial": 1,
     "trial_price": "5.00",
     "trial_period_length": 3,
     "trial_period_type": "day",
     "price": "105.00",
     "discount_price": null,
     "active": 1,
     "subscriptions_count": 1
   },
   "paid_number_counter": 1,
   "init_merchant_order_id": "w146138485"
 }
}

Subscription is stopped due to failed payments

If a recurring payment fails (for example due to insufficient funds), FasterPay will try to charge the customer again in 6 hours for up to 3 times. If the payment goes through, you will receive a recurring payment pingback. If all of the attempts fail, the subscription will be stopped and you will get the pingback below.

{
  "event": "subscription_stopped",
  "subscription": {
    "id": 100345508,
    "u_email": "john.smith@email.com",
    "recurring_id": 1005002001,
    "status": "Cancelled",
    "cancel_delay": 0,
    "currency_code": "USD",
    "trial": 1,
    "trial_price": "5.00",
    "trial_period_length": 3,
    "trial_period_type": "day",
    "counter": 1,
    "limit": 0,
    "failures": 0,
    "period_length": 10,
    "period_type": "day",
    "billing_type": 1,
    "price": "105.00",
    "date_active": 0,
    "date_start": 1533704765,
    "date_next": 1533963965,
    "date_end": 1565067965,
    "date_paid": 1533704765,
    "date_expired": 0,
    "date_cancelled": 1533704799,
    "date_stopped": 0,
    "created_at": 1533704765,
    "package_version_id": 213,
    "change_request": null,
    "package": {
      "id": 0,
      "sku_id": "your_product_sku_id",
      "name": "your product name",
      "currency_code": "USD",
      "period_length": 10,
      "period_type": "day",
      "recurring_limit": 0,
      "trial": 1,
      "trial_price": "5.00",
      "trial_period_length": 3,
      "trial_period_type": "day",
      "price": "105.00",
      "discount_price": null,
      "active": 1,
      "subscriptions_count": 1
    },
    "paid_number_counter": 1
  }
}

Subscription is cancelled

If a subscription is cancelled (for example by the customer), FasterPay we will send the pingback below:

{
  "event": "subscription_cancelled",
  "subscription": {
    "id": 100345508,
    "u_email": "john.smith@email.com",
    "recurring_id": 1005002001,
    "status": "Cancelled",
    "cancel_delay": 0,
    "currency_code": "USD",
    "trial": 1,
    "trial_price": "5.00",
    "trial_period_length": 3,
    "trial_period_type": "day",
    "counter": 1,
    "limit": 0,
    "failures": 0,
    "period_length": 10,
    "period_type": "day",
    "billing_type": 1,
    "price": "105.00",
    "date_active": 0,
    "date_start": 1533704765,
    "date_next": 1533963965,
    "date_end": 1565067965,
    "date_paid": 1533704765,
    "date_expired": 0,
    "date_cancelled": 1533704799,
    "date_stopped": 0,
    "created_at": 1533704765,
    "package_version_id": 213,
    "change_request": null,
    "package": {
      "id": 0,
      "sku_id": "your_product_sku_id",
      "name": "your product name",
      "currency_code": "USD",
      "period_length": 10,
      "period_type": "day",
      "recurring_limit": 0,
      "trial": 1,
      "trial_price": "5.00",
      "trial_period_length": 3,
      "trial_period_type": "day",
      "price": "105.00",
      "discount_price": null,
      "active": 1,
      "subscriptions_count": 1
    },
    "paid_number_counter": 1
  }
}

Step 5: Manage subscriptions via API.

If needed, you can manage subscriptions via API, for example when you need to cancel a subscription. Alternatively, you can use Subscription Management Tools in your FasterPay Business Account.


Step 6: Test.

Once you have completed implementation, go ahead and test it using the Test Credit Card numbers found in FasterPay’s Test Mode. You can turn on test mode by clicking the toggle in the header.


Step 7: Go Live.

Once you’re done, simply fill out your Business Profile and Go Live!