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
hash
string
Hash

Endpoint

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

Sample Request

<?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'
	)
);

echo $form;
?>

Endpoint

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

Sample Request

from fasterpay.gateway import Gateway

if __name__ == "__main__":

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

    payload = {
        "description": "Golden Ticket",
        "amount": "0.01",
        "currency": "EUR",
        "merchant_order_id": "xxxxx",
        "success_url": "https://yourcompanywebsite.com/success"
    }

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

    print paymentForm

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 Request is a HTTP POST Request from FasterPay to the Merchant’s Pingback URL. The data contained in the Pingback Request is a JSON object comprises of parameter related to the Payment Transaction Details.


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

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

Alternatively, pingback requests 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

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

Sample Pingback

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

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

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

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

Sample Pingback

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

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”)

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

Refunds

This API allows to issue a 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

Endpoint

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

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
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;
?>

Sample Pingback

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

Endpoint

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

Sample Request

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

Sample Pingback

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

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

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

Cancel Subscriptions

This API allows to issue a 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/<order-id>/cancel

Endpoint

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

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