API Reference

This API reference consists of all the APIs provided by FasterPay. If you have any suggestions or confusion about our reference pages, please create a issue directly on our Github.

Checkout Page

Custom Integration allows you to redirect your customer directly to the FasterPay widget. It is a browser to browser call where on selecting FasterPay option on the checkout page of your website the customer is redirected to the FasterPay widget.

Checkout Page Integration Parameters

Name Description
amount
required
string
Payment amount in 0000.00 format
currency
required
string
Payment currency in ISO 4217 format
description
required
string
Product description
api_key
required
string
FasterPay Public key
merchant_order_id
required
string
Merchant Order ID
email
string
Customer Email
first_name
string
Customer First Name
last_name
string
Customer Last Name
city
string
Customer City
zip
string
Customer Zip
success_url
string
Transaction Success page URL
Defining success_url for Android
pingback_url
string
If the pingback_url parameter is set and is valid, pingback will only be triggered to this URL. If the parameter is not set and is null / empty, the pingback will fallback to the default url set in Business Model settings.
hash
string
Hash
Refer: Calculating API Hash
sign_version
string
Signature version used to calculate FasterPay hash parameter.
This parameter is not mandatory if sign_version is v1
Possible values v2, v1.
Refer: Calculating API Hash

Endpoint

POST https://pay.fasterpay.com/payment/form

Sample Request

<?php

require_once('path/to/fasterpay-php/lib/autoload.php');

$gateway = new FasterPay\Gateway([
    'publicKey' => '<your-public-key>',
    'privateKey' => '<your-private-key>',
    'isTest' => 1,
]);

$form = $gateway->paymentForm()->buildForm(
    [
        'description' => 'Test order',
        'amount' => '10',
        'currency' => 'USD',
        'merchant_order_id' => time(),
        'success_url' => 'https://yourcompanywebsite.com/success',
        'pingback_url' => 'https://yourcompanywebsite.com/pingback',
        'sign_version' => 'v2' // to use version 1 please skip this param or set it 'v1'
    ],
    [
        'autoSubmit' => false,
        'hidePayButton' => false
    ]
);

echo $form;

Endpoint

POST https://pay.fasterpay.com/payment/form

Sample Request

from fasterpay.gateway import Gateway
import random

if __name__ == "__main__":
    gateway = Gateway("<your private key>", "<your public key>")

    parameters = {
        "payload": {
            "description": "Golden Ticket",
            "amount": "0.01",
            "currency": "EUR",
            "merchant_order_id": random.randint(1000, 9999),
            "success_url": "http://localhost:12345/success.php",
        },
        "auto_submit_form": True
    }

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

    print paymentForm

Endpoint

POST https://pay.fasterpay.com/payment/form

Sample Request

public class TransactionServlet extends HttpServlet {

    private Gateway gateway = Gateway.builder()
        .publicApi("<your public key>")
        .privateApi("<your private key>")
        .build();

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        PrintWriter writer = resp.getWriter();

        Form form = gateway.paymentForm()
            .amount("5.00")
            .currency("USD")
            .description("Golden ticket")
            .merchantOrderId(UUID.randomUUID().toString())
            .sign_version(SignVersion.VERSION_2)
            .isAutoSubmit(true);

        writer.println("<html><body>");
        writer.println(form.build());
        writer.println("</body></html>");
    }
}

Endpoint

POST https://pay.fasterpay.com/payment/form

Sample Request

class MainActivity : AppCompatActivity() {

    val fasterPay: FasterPay by lazy {
        FasterPay("<your public key>", true)
    }

    private fun requestPayment() {
        val form = gateWay.form()
            .amount("0.5")
            .currency("USD")
            .description("Golden Ticket")
            .merchantOrderId(UUID.randomUUID().toString())
            .successUrl("<your definition url>")

        startActivity(gateWay.prepareCheckout(this, form))
    }
}

Endpoint

POST https://pay.fasterpay.com/payment/form

Sample Request

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 "hash=<hash generated using the combination of post params and merchant private key>"

Pingbacks

A Pingback is a HTTP POST Request from FasterPay to the Merchant’s Pingback URL. The Pingback contains parameters related to the Payment Transaction Details.


Following are the list of parameters received by the merchant in a Pingback.

Name Description
event
string
Type of Event ex “payment”
payment_order.id
string
Payment Order ID generated in FasterPay
payment_order.merchant_order_id
string
Order ID generated by Merchant
payment_order.payment_system
string
Payment System Used to complete the Payment
1 - Credit Cards Payments
payment_order.status
string
Status of the Transaction (Success / Failed)
payment_order.paid_amount
double
Total Amount Paid by the Customer
payment_order.paid_currency
string
Currency in which the order was Paid
payment_order.merchant_net_revenue
double
Total Amount which is Settled to the Merchant.
payment_order.merchant_rolling_reserve
double
Amount which is kept for Security Purpose for Chargebacks
payment_order.fees
double
FasterPay Processing Fees
payment_order.date.date
string
Date & Time of Transaction in UTC
payment_order.date.timezone_type
integer
Timezone type used for Display
payment_order.date.timezone
string
Timezone used for the Display
user.firstname
string
First Name of the Customer
user.lastname
string
Last Name of the Customer
user.username
string
Username of the Customer
user.country.
string
Customer Country
user.email
string
E-Mail Address of the Customer
with_risk_check
boolean
If the Transaction is flagged as Risky by FasterPay
pingback_ts
integer
Unix Timestamp of the time when the pingback was sent

Pingbacks should be validated by calculating signature on the merchant end and comparing it with headers X-FasterPay-Signature. Header X-FasterPay-Signature-Version will contain the sign_version value passed during initiating Payment requests.

[Deprecated] Version 1: Pingbacks should be validated using the X-ApiKey header value which is the Private Key used to initiate the requests.

More information can be found in the documentation here

Example:

<?php

require_once('path/to/fasterpay-php/lib/autoload.php');

$gateway = new FasterPay\Gateway([
    'publicKey' => '<your-public-key>',
    'privateKey' => '<your-private-key>',
    'isTest' => 1,
]);

$signVersion = \FasterPay\Services\Signature::SIGN_VERSION_1;
if (!empty($_SERVER['HTTP_X_FASTERPAY_SIGNATURE_VERSION'])) {
    $signVersion = $_SERVER['HTTP_X_FASTERPAY_SIGNATURE_VERSION'];
}

$pingbackData = null;
$validationParams = [];

switch ($signVersion) {
    case \FasterPay\Services\Signature::SIGN_VERSION_1:
        $validationParams = ["apiKey" => $_SERVER["HTTP_X_APIKEY"]];
        $pingbackData = $_REQUEST;
        break;
    case \FasterPay\Services\Signature::SIGN_VERSION_2:
        $validationParams = [
            'pingbackData' => file_get_contents('php://input'),
            'signVersion' => $signVersion,
            'signature' => $_SERVER["HTTP_X_FASTERPAY_SIGNATURE"],
        ];
        $pingbackData = json_decode(file_get_contents('php://input'), 1);
        break;
    default:
        exit('NOK');
}

if (empty($pingbackData)) {
    exit('NOK');
}

if (!$gateway->pingback()->validate($validationParams)) {
    exit('NOK');
}

#TODO: Write your code to deliver contents to the End-User.
echo "OK";
exit();

Sample Pingback Data

{
    "event": "payment",
    "payment_order": {
        "id": 13339,
        "merchant_order_id": "8245",
        "payment_system": 1,
        "status": "successful",
        "paid_amount": 0.01,
        "paid_currency": "EUR",
        "merchant_net_revenue": -0.2608,
        "merchant_rolling_reserve": 0.0005,
        "fees": 0.2703,
        "date": {
            "date": "2019-07-11 10:56:03.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    },
    "user": {
        "firstname": "John",
        "lastname": "Doe",
        "username": "John-Doe-1@my.passport.io",
        "country": "IN",
        "email": "john+doe@gmail.com"
    },
    "with_risk_check": false,
    "pingback_ts": 1562842637
}

Example:

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"

Sample Pingback Data

{
    "event": "payment",
    "payment_order": {
        "id": 13339,
        "merchant_order_id": "8245",
        "payment_system": 1,
        "status": "successful",
        "paid_amount": 0.01,
        "paid_currency": "EUR",
        "merchant_net_revenue": -0.2608,
        "merchant_rolling_reserve": 0.0005,
        "fees": 0.2703,
        "date": {
            "date": "2019-07-11 10:56:03.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    },
    "user": {
        "firstname": "John",
        "lastname": "Doe",
        "username": "John-Doe-1@my.passport.io",
        "country": "IN",
        "email": "john+doe@gmail.com"
    },
    "with_risk_check": false,
    "pingback_ts": 1562842637
}

Example:

import spark.Service;

public class PingBackRoute implements Routes {

    private PingBack pingBack = new PingBack("<your private key");

    @Override
    public void define(Service service) {
        this.service = service;
        definePingbackRoutes();
    }

    @POST
    public void definePingbackRoutes() {
        service.post(BASE_PATH, ((request, response) -> {
            boolean isValid = pingBack.validation()
                .signVersion(Optional.ofNullable(request.headers(PingBack.X_FASTERPAY_SIGNATURE_VERSION)))
                .apiKey(Optional.ofNullable(request.headers(PingBack.X_API_KEY)))
                .signature(Optional.ofNullable(request.headers(PingBack.X_FASTERPAY_SIGNATURE)))
                .pingBackData(Optional.of(request.body()))
                .execute();
            if (isValid) {
                //process further with pingBack
                response.status(HttpStatus.OK_200);
                return response;
            } else {
                //process with invalid pingBack
                throw halt(HttpStatus.NOT_IMPLEMENTED_501);
            }
        }));
    }
}

Sample Pingback Data

{
    "event": "payment",
    "payment_order": {
        "id": 13339,
        "merchant_order_id": "8245",
        "payment_system": 1,
        "status": "successful",
        "paid_amount": 0.01,
        "paid_currency": "EUR",
        "merchant_net_revenue": -0.2608,
        "merchant_rolling_reserve": 0.0005,
        "fees": 0.2703,
        "date": {
            "date": "2019-07-11 10:56:03.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    },
    "user": {
        "firstname": "John",
        "lastname": "Doe",
        "username": "John-Doe-1@my.passport.io",
        "country": "IN",
        "email": "john+doe@gmail.com"
    },
    "with_risk_check": false,
    "pingback_ts": 1562842637
}

Example

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, \
    "pingback_ts": 1562842637
  }'
 https://your-pingback-url.com/pingback.php

Sample Pingback Data

{
    "event": "payment",
    "payment_order": {
        "id": 13339,
        "merchant_order_id": "8245",
        "payment_system": 1,
        "status": "successful",
        "paid_amount": 0.01,
        "paid_currency": "EUR",
        "merchant_net_revenue": -0.2608,
        "merchant_rolling_reserve": 0.0005,
        "fees": 0.2703,
        "date": {
            "date": "2019-07-11 10:56:03.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    },
    "user": {
        "firstname": "John",
        "lastname": "Doe",
        "username": "John-Doe-1@my.passport.io",
        "country": "IN",
        "email": "john+doe@gmail.com"
    },
    "with_risk_check": false,
    "pingback_ts": 1562842637
}

Pay Button Integration

Pay Button is a simple way to integrate FasterPay widget by adding the script to your page and providing the required parameters from the table below.

Pay Button Integration Parameters

Name Description
src
required
string
FasterPay pay.js library
https://pay.fasterpay.com/pay.js
amount
required
string
Payment amount in 0000.00 format
currency
required
string
Payment currency in ISO 4217 format
description
required
string
Product description
merchant
required
string
FasterPay Public key
success_url
string
Optional Custom Success page URL
size
string
Pay Button size (“sm”, “md” or “lg”)
target
string
Target defines how the checkout page will be shown to the users
(“iframe”, “newWindow”, “newTab”)

You can use the Pay Button Builder to generate your button code.

Pay Button integration does not require hash parameter to be sent in the API request.
In case the FasterPay Payment page responds with Wrong Hash please email integration@fasterpay.com to disable Hash param.

Refunds

This API allows to issue a POST request to refund a transaction.

Headers


Name Description
X-ApiKey
required
string
(header)
Merchant private key

Parameters


Name Description
amount
required
numeric
(formData)
Amount to be refunded

Endpoint

POST https://pay.fasterpay.com/payment/<order-id>/refund

Sample Request

<?phprequire_once('path/to/fasterpay-php/lib/autoload.php');

$gateway = new FasterPay\Gateway([
    'publicKey' => '<your-public-key>',
    'privateKey' => '<your-private-key>',
    'isTest' => 1,
]);

$orderId = '<your-order-id>';
$amount = '<refund-amount>';

try {
    $refundResponse = $gateway->paymentService()->refund($orderId, $amount);
} catch (FasterPay\Exception $e) {
    echo '<pre>';
    print_r($e->getMessage());
    echo '</pre>';
    exit();
}

if ($refundResponse->isSuccessful()) {
    echo 'Refunded ' . $amount;
} else {
    echo $refundResponse->getErrors()->getMessage();
}

Endpoint

POST https://pay.fasterpay.com/payment/<order-id>/refund

Sample request

from fasterpay.gateway import Gateway

if __name__ == "__main__":

    gateway = Gateway("<your private key>", "<your public key>")

    refundResponse = gateway.refund().process(orderId, 0.01)

    print refundResponse

Endpoint

POST https://pay.fasterpay.com/payment/<order-id>/refund

Sample Request

public class TransactionServlet extends HttpServlet {

    private Gateway gateway = Gateway.builder()
        .publicApi("<your public key>")
        .privateApi("<your private key>")
        .build();

        @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        PrintWriter writer = resp.getWriter();

        String orderId = req.getParameter("orderId");
        String amount = req.getParameter("amount");
        Response result = gateway.refund(orderId, Float.parseFloat(amount));
        writer.println("<html><body>");
        writer.println(Optional.of(result)
            .filter(response -> response.isSuccess())
            .map(response -> "Refund order " + orderId + " successfully")
            .orElse("Refund order " + orderId + " failed: " + result.getCode() + "- " + result.getMessage()));
        writer.println("</body></html>");
    }
}

Endpoint

POST https://pay.fasterpay.com/payment/<order-id>/refund

Sample Request

curl https://pay.fasterpay.com/payment/72186278162/refund \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]" \
-d "amount=10"

Recurring Billing

Recurring Billing allow Merchants to charge a User a specific amount after a specific time interval.

Integration Parameters

Subscriptions use some more parameters in conjunction with the custom integration parameters as described in Custom Integration. Paramters used to create subscriptions are detailed as below.

Name Description
recurring_name
required
string
Name of product/package of subscription
recurring_sku_id
required
string
SKU ID of product/package of subscription
recurring_period
required
string
Period of subscription (ex: 1w mean every one week, 1m mean every month, 2m mean every 2 month)
recurring_trial_amount
string
Trial price for trial period subscription
recurring_trial_period
string
Period of trial, ex 1m mean trial period one month
recurring_duration
string
Number of month subscription will run, by default it’s 6 months. If you put 0 it means the subscription will run until cancelled or stopped
Only Available for Direct Merchants

Endpoint

POST https://pay.fasterpay.com/payment/form

Sample Request

<?php

require_once('path/to/fasterpay-php/lib/autoload.php');

$gateway = new FasterPay\Gateway([
    'publicKey' => '<your-public-key>',
    'privateKey' => '<your-private-key>',
    'isTest' => 1,
]);

$form = $gateway->paymentForm()->buildForm(
    [
        'description' => 'Test order',
        'amount' => '10',
        'currency' => 'USD',
        'merchant_order_id' => time(),
        'success_url' => 'https://yourcompanywebsite.com/success',
        'recurring_name' => 'recurring1',
        'recurring_sku_id' => 'recurring1',
        'recurring_period' => '6m',
        'recurring_trial_amount' => '30',
        'recurring_trial_period' => '1m',
        'pingback_url' => 'https://yourcompanywebsite.com/pingback',
        'sign_version' => 'v2' // to use version 1 please skip this param or set it 'v1'
    ],
    [
        'autoSubmit' => false,
        'hidePayButton' => false
    ]
);

echo $form;

Sample Pingback Data

{
 "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"
 },
 "pingback_ts": 1562842637
}

Endpoint

POST https://pay.fasterpay.com/payment/form

Sample Request

from fasterpay.gateway import Gateway
from random import randint

if __name__ == "__main__":

    gateway = Gateway("<your private key>", "<your public key>")

    parameters = {
        "payload": {
            "description": "Golden Ticket",
            "amount": "10",
            "currency": "EUR",
            "merchant_order_id": randint(1000, 9999),
            "success_url": "http://localhost:12345/success.php",
            "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
        },
        "auto_submit_form": True
    }

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

    print paymentForm

Sample Pingback Data

{
 "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"
 },
 "pingback_ts": 1562842637
}

Endpoint

POST https://pay.fasterpay.com/payment/form

Sample Request

public class TransactionServlet extends HttpServlet {

    private Gateway gateway = Gateway.builder()
        .publicApi("<your public key>")
        .privateApi("<your private key>")
        .build();

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        PrintWriter writer = resp.getWriter();

        Form subscriptionsForm = gateway.subscriptionForm()
            .amount("1")
            .currency("USD")
            .description("Moonsoon festival")
            .merchantOrderId(UUID.randomUUID().toString())
            .recurringName("moonsoon")
            .recurringSkuId("festival")
            .recurringPeriod("3m")
            .sign_version(SignVersion.VERSION_2)
            .isAutoSubmit(true);

        writer.println("<html><body>");
        writer.println(subscriptionsForm.build());
        writer.println("</body></html>");
    }
}

Sample Pingback Data

{
 "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"
 },
 "pingback_ts": 1562842637
}

Endpoint

POST https://pay.fasterpay.com/payment/form

Sample Request

class MainActivity : AppCompatActivity() {

    val fasterPay: FasterPay by lazy {
        FasterPay("<your public key>", true)
    }

    private fun subscriptions() {
        val subscriptionsForm = gateWay.subscription()
            .amount("5")
            .currency("USD")
            .description("Test product description")
            .merchantOrderId(UUID.randomUUID().toString())
            .successUrl("http://fasterpay.datph")
            .recurringName("Test FP Recurring")
            .recurringSkuId("fp_test_recurring")
            .recurringPeriod("10d")
            .recurringTrialAmount("1")
            .recurringTrialPeriod("3d")

        startActivity(gateWay.prepareCheckout(this, subscriptionsForm))
    }
}

Sample Pingback Data

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

Endpoint

POST https://pay.fasterpay.com/payment/form

Sample Request

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>"

Sample Pingback Data

{
 "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"
 },
 "pingback_ts": 1562842637
}

Cancelling Subscriptions

This API allows to issue a POST request to cancel a recurring billing payment.

Headers


Name Description
X-ApiKey
required
string
(header)
Merchant private key

Endpoint

POST https://pay.fasterpay.com/api/subscription/<subscription-id>/cancel

Sample Request

<?phprequire_once('path/to/fasterpay-php/lib/autoload.php');

$gateway = new FasterPay\Gateway([
    'publicKey' => '<your-public-key>',
    'privateKey' => '<your-private-key>',
    'isTest' => 1,
]);
$subscriptionId = '<your-subscription-id>';

try {
    $cancellationResponse = $gateway->subscriptionService()->cancel($subscriptionId);
} catch (FasterPay\Exception $e) {
    echo '<pre>';
    print_r($e->getMessage());
    echo '</pre>';
    exit();
}

if ($cancellationResponse->isSuccessful()) {
    echo 'Canceled';
} else {
    echo $cancellationResponse->getErrors()->getMessage();
}

Endpoint

POST https://pay.fasterpay.com/api/subscription/<order-id>/cancel

Sample Request

from fasterpay.gateway import Gateway
from random import randint

if __name__ == "__main__":

    gateway = Gateway("<your private key>", "<your public key>")

    response = gateway.subscription().cancel(order_id=subscription_id)

    print response

Endpoint

POST https://pay.fasterpay.com/api/subscription/<subscription-id>/cancel

Sample Request

public class TransactionServlet extends HttpServlet {

    private Gateway gateway = Gateway.builder()
        .publicApi("<your public key>")
        .privateApi("<your private key>")
        .build();

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        PrintWriter writer = resp.getWriter();

        String orderId = req.getParameter("orderId");
        Response result = gateway.cancelSubscription(orderId);

        writer.println("<html><body>");
        writer.println(Optional.of(result)
            .filter(response -> response.isSuccess())
            .map(response -> "Cancel order " + orderId + " successfully")
            .orElse("Cancel order " + orderId + " failed: " + result.getCode() + "- " + result.getMessage()));
        writer.println("</body></html>");
    }
}

Endpoint

POST https://pay.fasterpay.com/api/subscription/<order-id>/cancel

Sample Request

curl https://pay.fasterpay.com/api/subscription/82173982713/cancel \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]"