☰

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.

To generate QR code, the request header must include Accept and the request parameter must include payment_flow.

Headers

Name Description
Accept
string
(header)		 QR code generation request header
Value: application/json

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
payment_flow
string		 QR code generation request parameter
Value user_qr
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>", True)

    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

const fasterpay = require('fasterpay-node');

let gateway = new fasterpay.Gateway({
    publicKey: '<your public key>',
    privateKey: '<your private key>',
    isTest: 1 // Use 1 for Test Method
});

app.get('/one-time', (req, res) => {
    let paymentForm = gateway.PaymentForm().buildForm({
        'description': 'Test order',
        'amount': '10',
        'currency': 'USD',
        'merchant_order_id': new Date().getTime().toString(),
        'sign_version': 'v2',
        'success_url': baseurl + '/success',
        'pingback_url': baseurl + '/pingback'
    },{
        'autoSubmit': false,
        'hidePayButton': false,
    });
    res.send(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>"

Order Detail parameters for Checkout

Order details parameters could be added as additional parameters in either Checkout Page or Recurring Billing API for extra needs. These values will be used in the Purchase receipt sent to the users upon completion of payment.

Parameters

Name Description
order_detail[sub_total]
required if items are present
double		 Total amount to be paid by user excluding Tax.
order_detail[tax]
double		 Total Tax to be paid by end user for the purchase.
order_detail[shipping_fee]
required if items are present
double		 Total Shipping fee to be paid by the customer.
order_detail[items][index][name]
required if items are present
string		 Name of the item the user purchased on the website
Here index is the position of the item in the array.
order_detail[items][index][sku]
required if items are present
string		 SKU of the item user purchased on the website.
order_detail[items][index][description]
required if items are present
string		 Description of the item user purchased on the website.
order_detail[items][index][quantity]
required if items are present
int		 Quantity of the item user purchased on the website.
order_detail[items][index][price]
required if items are present
double		 Price of the item user purchased on the website.
order_detail[items][index][image]
string		 Image url of the item user purchased on the webiste.

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',
        'order_details' => array(
          "sub_total" => 19,
          "tax" => 2,
          "shipping_fee" => 5,
          "items" => array(
            array(
              "name" => "Christmas Tree",
              "sku" => "sb_87193",
              "description" => "Gift For Children-DIY felt christmas tree",
              "quantity" => 1,
              "price" => 19
            )
          )
        ),
        'sign_version' => 'v2' // to use version 1 please skip this param or set it 'v1'
    ],
    [
        'autoSubmit' => false,
        'hidePayButton' => false
    ]
);

echo $form;

Transaction 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>", True)

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:

const fasterpay = require('fasterpay-node');

let gateway = new fasterpay.Gateway({
    publicKey: '<your public key>',
    privateKey: '<your private key>',
    isTest: 1 // Use 1 for Test Method
});

app.post("/pingback", (req, res) => {
    let html = 'NOK';
    if(gateway.Pingback().validate(req)){
        html = 'OK';
    }
    res.send(html);
});

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
}

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
failure_url
string		 Optional Custom Failure page URL
theme
string		 Pay Button theme (“light”, “dark” or “yellow”)
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.

Pay Button For Recurring Billing 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
recurringName
required
string		 Name of product/package of subscription
recurringSkuId
required
string		 SKU ID of product/package of subscription
recurringPeriod
required
string		 Period of subscription (ex: 1w mean every one week, 1m mean every month, 2m mean every 2 month)
recurringTrialAmount
string		 Trial price for trial period subscription
recurringTrialPeriod
string		 Period of trial, ex 1m mean trial period one month
recurringDuration
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
success_url
string		 Optional Custom Success page URL
failure_url
string		 Optional Custom Failure page URL
theme
string		 Pay Button theme (“light”, “dark” or “yellow”)
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”)

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>", True)

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

    print refundResponse

Endpoint

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

Sample Request

const fasterpay = require('fasterpay-node');

let gateway = new fasterpay.Gateway({
    publicKey: '<your public key>',
    privateKey: '<your private key>',
    isTest: 1 // Use 1 for Test Method
});

app.get('/refund', (req, res) => {
    let response = gateway.Payment().refund(req.query.id, req.query.amount);
    let html = 'NOK';
    if(response != false && 'success' in response){ 
        html = 'OK';
    }
    res.send(html);
});

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"

Refund Pingbacks

FasterPay supports the ability to refund charges made to your account, either in full or in partial. Whenever a refund is initated through the dashboard or by our agents, you will receive a pingback to the mentioned Pingback URL provided in your Merchant Area under Business Model settings.


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

Name Description
event
string		 Type of Event
refund - for Full Refund
partial_refund - for Partial Refund
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 method used to complete the Payment and through which the refund will be made
1 - Credit or Debit card
payment_order.status
string		 Status of the Refund
reversal_refunded - for Full Refund
reversal_refunded_partially - for Partial Refund
payment_order.total_refunded_amount
double		 Total Amount refunded to the Customer
payment_order.refund_amount
string		 Amount requested to be refunded
payment_order.refund_fee
double		 Total Fee charged by FasterPay for Refunds
payment_order.reference_id
double		 Refund reference ID
payment_order.refund_date
double		 Date when refund was processed
pingback_ts
int		 Unix Timestamp of the time when 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

Sample Partial Refund Pingback Data

{
  "event":"partial_refund",
  "payment_order":{
    "id":3590617,
    "merchant_order_id":"w197890832",
    "payment_system":1,
    "status":"reversal_refunded_partially",
    "total_refunded_amount":"0.5000",
    "refund_amount":"0.50",
    "refund_fee":"0.66",
    "reference_id":21231231,
    "refund_date":1568105705
  },
  "pingback_ts":1568105707
}

Sample Full Refund Pingback Data

{
"event":"refund",
"payment_order":{
  "id":14551,
  "merchant_order_id":"8568462082136_1568114062",
  "payment_system":1,
  "status":"reversal_refunded",
  "total_refunded_amount":"10.0000",
  "refund_amount":"10.00",
  "refund_fee":"0.00",
  "reference_id":6713131,
  "refund_date":1568119025
},
"pingback_ts":1568119066
}

Sample Partial Refund Pingback Data

{
  "event":"partial_refund",
  "payment_order":{
    "id":3590617,
    "merchant_order_id":"w197890832",
    "payment_system":1,
    "status":"reversal_refunded_partially",
    "total_refunded_amount":"0.5000",
    "refund_amount":"0.50",
    "refund_fee":"0.66",
    "reference_id":21231231,
    "refund_date":1568105705
  },
  "pingback_ts":1568105707
}

Sample Full Refund Pingback Data

{
"event":"refund",
"payment_order":{
  "id":14551,
  "merchant_order_id":"8568462082136_1568114062",
  "payment_system":1,
  "status":"reversal_refunded",
  "total_refunded_amount":"10.0000",
  "refund_amount":"10.00",
  "refund_fee":"0.00",
  "reference_id":6713131,
  "refund_date":1568119025
},
"pingback_ts":1568119066
}

Sample Partial Refund Pingback Data

{
  "event":"partial_refund",
  "payment_order":{
    "id":3590617,
    "merchant_order_id":"w197890832",
    "payment_system":1,
    "status":"reversal_refunded_partially",
    "total_refunded_amount":"0.5000",
    "refund_amount":"0.50",
    "refund_fee":"0.66",
    "reference_id":21231231,
    "refund_date":1568105705
  },
  "pingback_ts":1568105707
}

Sample Full Refund Pingback Data

{
"event":"refund",
"payment_order":{
  "id":14551,
  "merchant_order_id":"8568462082136_1568114062",
  "payment_system":1,
  "status":"reversal_refunded",
  "total_refunded_amount":"10.0000",
  "refund_amount":"10.00",
  "refund_fee":"0.00",
  "reference_id":6713131,
  "refund_date":1568119025
},
"pingback_ts":1568119066
}

Sample Partial Refund Pingback Data

{
  "event":"partial_refund",
  "payment_order":{
    "id":3590617,
    "merchant_order_id":"w197890832",
    "payment_system":1,
    "status":"reversal_refunded_partially",
    "total_refunded_amount":"0.5000",
    "refund_amount":"0.50",
    "refund_fee":"0.66",
    "reference_id":21231231,
    "refund_date":1568105705
  },
  "pingback_ts":1568105707
}

Sample Full Refund Pingback Data

{
"event":"refund",
"payment_order":{
  "id":14551,
  "merchant_order_id":"8568462082136_1568114062",
  "payment_system":1,
  "status":"reversal_refunded",
  "total_refunded_amount":"10.0000",
  "refund_amount":"10.00",
  "refund_fee":"0.00",
  "reference_id":6713131,
  "refund_date":1568119025
},
"pingback_ts":1568119066
}

Sample Partial Refund Pingback Data

{
  "event":"partial_refund",
  "payment_order":{
    "id":3590617,
    "merchant_order_id":"w197890832",
    "payment_system":1,
    "status":"reversal_refunded_partially",
    "total_refunded_amount":"0.5000",
    "refund_amount":"0.50",
    "refund_fee":"0.66",
    "reference_id":21231231,
    "refund_date":1568105705
  },
  "pingback_ts":1568105707
}

Sample Full Refund Pingback Data

{
"event":"refund",
"payment_order":{
  "id":14551,
  "merchant_order_id":"8568462082136_1568114062",
  "payment_system":1,
  "status":"reversal_refunded",
  "total_refunded_amount":"10.0000",
  "refund_amount":"10.00",
  "refund_fee":"0.00",
  "reference_id":6713131,
  "refund_date":1568119025
},
"pingback_ts":1568119066
}

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>", True)

    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

const fasterpay = require('fasterpay-node');

let gateway = new fasterpay.Gateway({
    publicKey: '<your public key>',
    privateKey: '<your private key>',
    isTest: 1 // Use 1 for Test Method
});

app.get('/subscribe', (req, res) => {
	let paymentForm = gateway.PaymentForm().buildForm({
        'description': 'Test order',
        'amount': '0.10',
        'currency': 'USD',
        'merchant_order_id': new Date().getTime().toString(),
        'sign_version': 'v2',
        'recurring_name': 'recurring1',
        'recurring_sku_id': 'recurring1',
        'recurring_period': '6m',
        'recurring_trial_amount': '0.10',
        'recurring_trial_period': '1m',
        'recurring_duration': '0',
        'success_url': baseurl + '/success',
        'pingback_url': baseurl + '/pingback'
	},{
		'autoSubmit': false,
		'hidePayButton': false,
	});
    res.send(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>", True)

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

    print response

Endpoint

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

Sample Request

const fasterpay = require('fasterpay-node');

let gateway = new fasterpay.Gateway({
    publicKey: '<your public key>',
    privateKey: '<your private key>',
    isTest: 1 // Use 1 for Test Method
});

app.get('/cancel_subscription', (req, res) => {
    let response = gateway.Subscription().cancel(req.query.id);
    let html = 'NOK';
    if(response != false && 'success' in response){ 
        html = 'OK';
    }
    res.send(html);
});

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

Delivery Confirmation API

Delivery Confirmation API allows you to notify FasterPay about successful delivery of the purchased item(s) to the user. This information helps us resolve dispute cases and refund requests in the fastest and the most efficient manner.

The required parameters are different with the type of your products, refer to digital or physical.

Endpoint

POST http://pay.fasterpay.com/api/v1/deliveries

Endpoint

POST http://pay.fasterpay.com/api/v1/deliveries

Endpoint

POST http://pay.fasterpay.com/api/v1/deliveries

Digital

Parameters

Parameter Description
payment_order_id
required
string		 reference ID of the transaction. It can be obtained from parameter payment_order.id in pingback request.
merchant_reference_id
required
string		 The order ID of the transaction in your system.
type
required
string		 Type of delivery, required to be set as digital.
sign_version
required
string		 Should be “v2”.
status
required
string		 Refer to Status.
reason
string		 Additional description for the status updated. It can be set as null if it is not convenient to provide.
refundable
required
string		 Either true or false. Whether the order is refundable at this stage.
details
required
string		 Description of order status which is showed to and recipient.
product_description
string		 Description of the new product in case of subsitution or change.
shipping_address[email]
required
string		 The email address of your customers.
notify_user
boolean		 Send an email to the user to notify the status of their delivery.
hash
required
string		 Hash Signature calculated using “v2” Signature calculation algorithm
Refer: Generating API Hash.

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,
]);

$payload = array(
  "payment_order_id" => 09281391,
  "merchant_reference_id" => "ws897321",
  "sign_version" => "v2",
  "status" => "order_placed",
  "refundable" => 1,
  "notify_user" => 1,
  "product_description" => "Golden Ticket",
  "details" => "Product Details go here",
  "reason" => "Shipped Today",
  "estimated_delivery_datetime" => date('Y-m-d H:i:s O', strtotime("+1 day")),
  "carrier_tracking_id" => "901389012830918301",
  "carrier_type" => "FedEx",
  "shipping_address" => array(
    "country_code" => "US",
    "city" => "San Francisco",
    "zip" => "91004",
    "state" => "CA",
    "street" => "Market Street",
    "phone" => 14159883933,
    "first_name" => "Jon",
    "last_name" => "Doe",
    "email" => "jon.doe@example.com"
  ),
  "type" => "physical",
  "public_key" => $gateway->getConfig()->getPublicKey(),
);

$payload["hash"] = $gateway->signature()->calculateWidgetSignature($payload);

$ch = curl_init($gateway->getConfig()->getApiBaseUrl() . '/api/v1/deliveries');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($payload));

$response = json_decode(curl_exec($ch), true);

echo "<pre>"; print_r($response); echo "</pre>";

Sample Request

from fasterpay.gateway import Gateway

if __name__ == "__main__":

    # Initialize the Gateway
    gateway = Gateway("<YOUR_PRIVATE_KEY>", "<YOUR_PUBLIC_KEY>", True)

    # Prepare Delivery Information
    deliveryInfo = {
        "payment_order_id": "4191647",
        "merchant_order_id": "1572519862",
        "type": "digital",
        "public_key": gateway.get_config().get_public_key(),
        "status": "order_placed",
        "refundable": 1,
        "details": "Order placed today",
    }
    deliveryInfo["shipping_address[email]"]="prashant@paymentwall.com"

    deliverResponse = gateway.transaction().deliver(deliveryInfo)

    print deliverResponse

Sample Request

let deliveryInfo = {
      "payment_order_id": '88777999',
      "merchant_reference_id": '1581593514527',
      "type": 'digital',
      "status": 'order_placed',
      "refundable": true,
      "details": 'Order Placed Today',
      "product_description": 'Golden Ticket',
      "public_key": gateway.getConfig().getPublicKey(),
      "shipping_address": {
        "email": 'jon.doe@example.com',
      },
      "notify_user": true
    };

    let response = gateway.Payment().deliver(deliveryInfo);

Physical

Parameters

Parameter Description
payment_order_id
required
string		 reference ID of the transaction. It can be obtained from parameter payment_order.id in pingback request.
merchant_reference_id
required
string		 The order ID of the transaction in your system.
type
required
string		 Type of delivery, required to be set as physical.
sign_version
required
string		 Should be “v2”.
status
required
string		 Refer to Status.
estimated_delivery_datetime
required
date		 Estimated delivery date of the order. Format: 2017/01/15 15:04:55 +0500.
estimated_update_datetime
date		 When the next status is planned to update. Format: 2017/01/15 15:04:55 +0500.
reason
string		 Additional description for the status updated. It can be set as null if it is not convenient to provide.
refundable
required
string		 Either true or false. Whether the order is refundable at this stage.
attachments
array		 Array attachments of the proofs of delivery. URL of pictures is expected.
details
required
string		 Description of order status which is showed to and recipient.
product_description
string		 Description of the new product in case of subsitution or change.
carrier_tracking_id
required
string		 Tracking ID / Shipment Order of the Physical goods.
carrier_type
required
string		 String. Name of the Shipping carrier, e.g. FedEx.
carrier_tracking_url
string		 Tracking url provided by the carrier.
shipping_address[email]
required
string		 The email address of your customers.
shipping_address[country_code]
required
string		 Shipping address country, ISO alpha-2 code.
shipping_address[city]
required
string		 Shipping address city.
shipping_address[zip]
required
string		 Shipping address zip/postal code.
shipping_address[state]
required
string		 Shipping address state or province.
shipping_address[street]
required
string		 Shipping address street.
shipping_address[phone]
required
string		 Phone number of the recipient.
shipping_address[first_name]
required
string		 Firstname of the recipient.
shipping_address[last_name]
required
string		 Lastname of the recipient.
notify_user
boolean		 Send an email to the user to notify the status of their delivery.
hash
required
string		 Hash Signature calculated using “v2” Signature calculation algorithm
Refer: Generating API Hash.

Sample success response

{
  "code": "00",
  "message": [],
  "count": 1,
  "data": [
    {
      "id": 51,
      "payment_order_id": 09281391,
      "merchant_reference_id": "ws897321",
      "sign_version": "v2",
      "refundable": true,
      "shipping_address": {
        "email": "jon.doe@example.com",
        "country_code": "US",
        "city": "San Francisco",
        "zip": "91004",
        "state": "CA",
        "street": "Market street",
        "phone": "14159883933",
        "first_name": "Jon",
        "last_name": "Doe"
      },
      "notify_user": true,
      "details": "Product Details go here",
      "product_description": "Golden Ticket",
      "status": "order_placed",
      "reason": "Shipped Today",
      "type": "physical",
      "estimated_delivery_datetime": "2019/11/09 01:04:55 +0000",
      "estimated_update_datetime": null,
      "carrier_tracking_id": "901389012830918301",
      "carrier_type": "FedEx",
      "created_at": "2019/11/04 10:29:03 +0000"
    }
  ]
}

Sample failed response

{
  "code": "01",
  "message": [
    {
      "message":"This payment order does not exist or does not belong to your account or not success payment."
    }
  ],
  "count": 0,
  "data": []
}

Sample success response

{
  "code": "00",
  "message": [],
  "count": 1,
  "data": [
    {
      "id": 51,
      "payment_order_id": 09281391,
      "merchant_reference_id": "ws897321",
      "sign_version": "v2",
      "refundable": true,
      "shipping_address": {
        "email": "jon.doe@example.com",
        "country_code": "US",
        "city": "San Francisco",
        "zip": "91004",
        "state": "CA",
        "street": "Market street",
        "phone": "14159883933",
        "first_name": "Jon",
        "last_name": "Doe"
      },
      "notify_user": true,
      "details": "Product Details go here",
      "product_description": "Golden Ticket",
      "status": "order_placed",
      "reason": "Shipped Today",
      "type": "physical",
      "estimated_delivery_datetime": "2019/11/09 01:04:55 +0000",
      "estimated_update_datetime": null,
      "carrier_tracking_id": "901389012830918301",
      "carrier_type": "FedEx",
      "created_at": "2019/11/04 10:29:03 +0000"
    }
  ]
}

Sample failed response

{
  "code": "01",
  "message": [
    {
      "message":"This payment order does not exist or does not belong to your account or not success payment."
    }
  ],
  "count": 0,
  "data": []
}

Sample success response

{
  "code": "00",
  "message": [],
  "count": 1,
  "data": [
    {
      "id": 51,
      "payment_order_id": 09281391,
      "merchant_reference_id": "ws897321",
      "sign_version": "v2",
      "refundable": true,
      "shipping_address": {
        "email": "jon.doe@example.com",
        "country_code": "US",
        "city": "San Francisco",
        "zip": "91004",
        "state": "CA",
        "street": "Market street",
        "phone": "14159883933",
        "first_name": "Jon",
        "last_name": "Doe"
      },
      "notify_user": true,
      "details": "Product Details go here",
      "product_description": "Golden Ticket",
      "status": "order_placed",
      "reason": "Shipped Today",
      "type": "physical",
      "estimated_delivery_datetime": "2019/11/09 01:04:55 +0000",
      "estimated_update_datetime": null,
      "carrier_tracking_id": "901389012830918301",
      "carrier_type": "FedEx",
      "created_at": "2019/11/04 10:29:03 +0000"
    }
  ]
}

Sample failed response

{
  "code": "01",
  "message": [
    {
      "message":"This payment order does not exist or does not belong to your account or not success payment."
    }
  ],
  "count": 0,
  "data": []
}

Status

For physical delivery, FasterPay requires the following statuses to be communicated via the Delivery Confirmation API:

  • order_placed
  • package_prepared
  • order_shipped
  • delivered

Merchants are encouraged to send all other applicable statuses. This will keep the end-users and our support and risk teams informed of the actual status of the order and improve the user experience.

Possible Values

order_placed Order has been placed within merchants system. This status should be sent immediately after receiving a pingback.
order_preparing
physical goods only		 Merchant started to look for ordered item in stock, processing the order.
package_prepared
physical goods only		 Merchant has prepared the package and it’s waiting to be shipped. The tracking ID is known at this point.
order_shipped
physical goods only		 When the order is shipped.
out_for_delivery
physical goods only		 When the order is out for delivery.
delivered Item has been delivered to the end-user. Attachment of delivery proof is expected in this case.
order_rejected
physical goods only		 When the user rejects the order at the time of delivery.
consumed
digital goods only		 Item is consumed by the end-user. Eg: activation keys, in-game virtual currency.
waiting_user_action
physical goods only		 User’s action is requested to complete the delivery. Eg: check the item or pick it up.
delayed Delay in delivery. Parameter reason is required to specify the cause.
failed_will_retry Delivery to end user failed. Waiting for retry.
order_cancelled
physical goods only		 Order has been cancelled, waiting for refund or substitution.Parameter reason is required to specify the cause. Eg: out of stock.
retry_started Attempt to retry on delivery.
refund_issued The original payment has been refunded.Details parameter should include refund information.

Response Codes

Possible Values

Code Description
00 Success
01 This payment order does not exist or not belong to your account or not success payment.
02 Invalid signature.
03 Delivery is complete.
04 Failed validation.
05 Empty tracking data sent.
06 Empty Physical parameters sent when change from digital to physical.
07 Update wrong status for physical or digital goods.
99 Other errors. Please send an email to integration@fasterpay.com with the error information.

FasterPay’s Delivery Confirmation API only uses v2 signature version, in case if you are using Version 1 of our SDK, we request you to upgrade to our latest SDKs from Github Repo

Commission Split Payment API

FasterPay Commission split payment is a feature that is aimed at platforms or marketplaces. The following parties are involved

  • FasterPay
  • Platform
  • Seller
  • Buyer

Authentication

This is a secret key assigned to you business you can get the key here: https://dashboard.fasterpay.com/processing/integration or under FasterPay Processing > Integration section.

  • Required header: x-api-key:your_private_key

Payment endpoints Base Url

Live

  • Base URL: https://pay.fasterpay.com

Sandbox

  • Base URL: https://sandbox.pay.fasterpay.com

Connect account endpoints Base Url

  • Base URL: https://business.fasterpay.com

Connect FasterPay Account APIs

Consent - GET /api/v1/connect/authorize

Request
Parameter Description
response_type
required
string		 Auth flow, code for now
scope
required
string		 Access requested, use comma separate format for multiple value
client_id
required
string		 Client ID
redirect_url
required
string		 Url to redirect back when authenticated and authorized
state
string		 Random string, returned with redirect_url
Parameter Description
code
string		 Authntication code, use to exchange access token, only available if user accepted in consent screen
state
string		 State param from authorize endpoint
error
string		 Error message, only available if user denied in consent screen

Fetch Access Token - POST /api/v1/connect/tokens

Request
Parameter Description
auth_code
string		 Returned with redirect url, required when exchange auth_code to access_token
refresh_token
string		 Required when refresh access_token
client_secret
required
string		 To detect which client is request access token
Response
Parameter Description
access_token
string		 Access token to access APIs
E.g: User profile API
refresh_token
string		 Token to exchange new access_token if needed, just return at first time exchanging access_token with auth_code until it expired or revoked
expires_at
string		 Access token expire time (UTC)
scope
string		 Requested access

Get User Data - POST /api/v1/connect/me

Request
Parameter Description
authentication
required
string		 Authentication header. E.g: Authentication: Bearer access_token_here
Response
Parameter Description
id
required
string		 User ID
first_name
required
string		 User firstname
last_name
required
string		 User lastname
phone
required
string		 User phone number
email
required
string		 User email
address
required
string		 User address
city
required
string		 User city
country
required
string		 User country

Payment APIs

Create Payment - POST /payment/form

Request
Parameter Description
is_escrow_payment
boolean		 Authentication header.
E.g: Authentication: Bearer access_token_here
splits.*.access_token
required
string		 List of access_token
splits.*.account_id
required
string		 List of account_id
splits.*.commission
required
double		 List of commission
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
Response

NOTE: This API will initialize the widget so no response here

Update funds splitting - POST /payment/{id}/split

Request
Parameter Description
*.commission
required
double		 List of commisison
*.account_id
required
string		 List of account_id
Response
Parameter Description
success
required
boolean		 Determines whether the request is success or not
error
string		 Error message

Fulfill - POST /payment/{id}/fulfill

Response
Parameter Description
success
required
boolean		 Determines whether the request is success or not
error
string		 Error message

Refund - POST /payment/{id}/refund

Request
Parameter Description
return_transfer
boolean		 This determines whether FasterPay will try to get the funds back from the seller to credit the platform based on the percentage of the reversed amount
amount
required
double		 Refund amount
Response
Parameter Description
success
required
boolean		 Determines whether the request is success or not
data.id
string		 Payment Order ID generated in FasterPay
data.merchant_order_id
string		 Order ID generated by Merchant
data.payment_system
string		 Payment method used to complete the Payment and through which the refund will be made
1 - Credit or Debit card
data.status
string		 Status of the Refund
reversal_refunded - for Full Refund
reversal_refunded_partially - for Partial Refund
data.total_refunded_amount
double		 Total Amount refunded to the Customer
data.refund_amount
string		 Amount requested to be refunded
data.refund_fee
double		 Total Fee charged by FasterPay for Refunds
data.reference_id
double		 Refund reference ID
data.refund_date
double		 Date when refund was processed

Pingbacks

Request
Parameter Description
event
string		 Type of Event
E.g: payment, pending_fulfillment, fulfilled
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
E.g: successful, pending_fulfillment, fulfilled
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
payment_order.commission.*.amount
double		 Timezone used for the Display
payment_order.commission.*.balance_type
string		 Timezone used for the Display
E.g: pending, available
payment_order.commission.*.reverse_amount
double		 Timezone used for the Display
payment_order.commission.*.account_id
string		 Timezone used for the Display
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

Mass Payout API

You can now initiate fund transfers from your FasterPay account to your users/senders/vendors etc. via our Mass Payout API either to their FasterPay accounts or to their bank accounts directly in one single batch.

Prior to initiating mass payouts requests, please make sure to have sufficient balance in your FasterPay accounts.

Authentication

Obtain the required secret key in https://dashboard.fasterpay.com/processing/integration or via the FasterPay Business Center → FasterPay Processing → Integration section.

  • Required header: X-ApiKey:your_private_key

Create Payout

You can initiate one or multiple payouts in a single request. You can pass the information of the payout in the payout object.

Headers

Name Description
X-ApiKey
required
string		 Merchant private key


Parameters

Parameter Description
source_currency
required
string		 Currency of the account in which you need to have sufficient balance to create the payout.
Currency code in ISO-4217 Format.
template
required
string		 The destination of the payout to be credited. It can be either bank_account or wallet
payouts
required
array		  
Payout Object  
amount
required
Amount of the transfer.
amount_currency
required
string		 The currency of the amount value indicated earlier. Amount currency can only be either the source_currency or the target_currency.
Currency code in ISO-4217 Format.
target_currency
required
string		 The currency which will be sent out by FasterPay. If the target_currency is different compared to the source_currency (the currency of the FasterPay account which you want to fund this transfer), then FasterPay will perform FX conversion.
Currency code in ISO-4217 Format.
receiver_type
required		 Receiver type of the payout, which could be one of the following values:
private - the recipient possesses / will create a personal FasterPay account with the email indicated above.
business- the recipient possesses / will create a business FasterPay account with the email indicated above.
receiver_full_name
required
string		 Full name of the recipient (maximum 255 characters).
receiver_email
required
email		 Email of the recipient.
bank_beneficiary_country
Optional/required
string		 required if template=bank_account
Country of the recipient. Only a 2-letter country code (based on ISO 3166-alpha 2) should be used for this field. E.g. “DE” should be used instead of “Germany”. Note that this field is NOT for the country of the recipient’s bank. The recipient and the recipient’s bank can be in 2 different countries.
bank_beneficiary_address
Optional/required
string		 required if template=bank_account
Address of the recipient (maximum 70 characters). Note, this is NOT the address of the recipient’s bank.
bank_account_number
Optional/required
string		 required if template=bank_account
This field (maximum 34 characters) is based on the specific bank transfer type, the value in this field should be the recipient’s: IBAN (International Bank Account Number). Or, Bank account number.
bank_swift_code
Optional/required
string		 required if template=bank_account
Recipient’s SWIFT (Society for Worldwide Interbank Financial Telecommunication) code (maximum 11 characters).
bank_name
Optional/required
string		 required if template=bank_account
Name of the recipient’s bank (maximum 70 characters)
corresponding_bank_swift_code
optional
string		 Please only use this field (maximum 11 characters) when specifically instructed.
additional_information
optional
string		 Any information (maximum 255 characters) which you want to note with the FasterPay team. This won’t be shown in any reports.
reference_id
optional
string
The unique reference ID (maximum 50 characters) in your system.
status
enum
Status of the payout, which could be one of the following values:
submitted: the initial status after the payout is created.
pending: when the money has been successfully deducted from the sender balance but the payout is pending for further checks by FasterPay.
failed: when the money cannot be deducted from the sender balance successfully.
success: when the payout has successfully been sent to the receiver.
rejected: when the payout is rejected by FasterPay.
description
optional
The detailed explanation of why the payout is failed or rejected.

Endpoint

POST https://business.fasterpay.com/api/external/payouts

Sample request data

{
  "source_currency": "EUR",
  "template": "wallet",
  "payouts": [
    {
      "amount_currency": "EUR",
      "reference_id": "payout_123",
      "amount": "100",
      "target_currency": "EUR",
      "receiver_full_name": "Firstname Lastname",
      "receiver_email": "email@fasterpay.com",
      "receiver_type":"private"
    }
  ]
}

Sample success response

{
  "success": true,
  "data": {
    "payouts": [
      {
        "id": "SM-210701-9JK7",
        "reference_id": "payout_123",
        "status":"submitted",
        "description": null,
        "created_at": "2021-07-09 05:35:03",
        "updated_at": "2021-07-09 06:50:59",
        "payout_method_type": "wallet",
        "receiver_type": "private",
        "receiver_email": "email@fasterpay.com",
        "receiver_full_name": "Firstname Lastname",
        "amounts": {
          "source_amount": "100",
          "source_currency": "EUR",
          "fee": 7.6,
          "fee_currency": "EUR",
          "converted_amount": "92.40",
          "rate": 1,
          "target_amount": "92.40",
          "target_currency": "EUR"
        }
      }
    ]
  }
}

Payout pingbacks

After you submitted a payout with a reference_id, there will be pingback events sent back to you to indicate the status transition for the payout.


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

Parameters

Parameter Description
event payout
pingback_ts Unix Timestamp of the time when Pingback was sent
payout The payout object

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.

More information can be found in the documentation here

Pingback sameple

{
  "event": "payout",
  "pingback_ts": 1631268709,
  "payout": {
    "id": "SM-210910-CF1B",
    "reference_id": "8",
    "created_at": "2021-09-10 10:11:44",
    "updated_at": "2021-09-10 10:11:49",
    "payout_method_type": "wallet",
    "description": "Your balance is not sufficient to perform this action",
    "status": "failed",
    "receiver_full_name": "Firstname Lastname",
    "receiver_email": "email@fasterpay.com",
    "receiver_type":"private",
    "amounts": {
      "source_amount": "1.86",
      "source_currency": "GBP",
      "fee": 0.36,
      "fee_currency": "GBP",
      "converted_amount": "1.50",
      "rate": 1,
      "target_amount": "1.50",
      "target_currency": "GBP"
    }
  }
}

Payout Details

You can fetch the details of a particular payout by sending the data.id in the URL received from the Payout List API.

Headers

Name Description
X-ApiKey
required
string		 Merchant private key

Endpoint

GET https://business.fasterpay.com/api/external/payouts/SM-210701-8UJ7

Sample success response

{
  "success": true,
  "data": {
    "id": "SM-210701-8UJ7",
    "reference_id": "payout_123",
    "created_at": "2021-07-09 05:35:03",
    "updated_at": "2021-07-09 06:50:59",
    "payout_method_type": "wallet",
    "receiver_type": "private",
    "receiver_email": "email@fasterpay.com",
    "receiver_full_name": "Firstname Lastname",
    "description": "Your balance is not sufficient to perform this action",
    "status": "failed",
    "amounts": {
      "source_amount": "100",
      "source_currency": "EUR",
      "fee": 7.6,
      "fee_currency": "EUR",
      "converted_amount": "92.40",
      "rate": 1,
      "target_amount": "92.40",
      "target_currency": "EUR"
    }
  }
}

Payout List

You can use this API to fetch all the Payouts created for your account. Make sure to pass your private key in the header to fetch payouts of your business account.

Headers

Name Description
X-ApiKey
required
string		 Merchant private key

Endpoint

GET https://business.fasterpay.com/api/external/payouts

Sample success response

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "SM-210701-9JK7",
        "reference_id": "payout_123",
        "description": "Your balance is not sufficient to perform this action",
        "status": "failed",
        "created_at": "2021-07-09 05:35:03",
        "updated_at": "2021-07-09 06:50:59",
        "payout_method_type": "wallet",
        "receiver_type": "private",
        "receiver_email": "email@fasterpay.com",
        "receiver_full_name": "Firstname Lastname",
        "amounts": {
          "source_amount": "100",
          "source_currency": "EUR",
          "fee": 7.6,
          "fee_currency": "EUR",
          "converted_amount": "92.40",
          "rate": 1,
          "target_amount": "92.40",
          "target_currency": "EUR"
        }
      },
      {
        "id": "SM-210701-8UJ7",
        "reference_id": "payout_124",
        "description": null,
        "status": "success",
        "created_at": "2021-07-09 05:35:03",
        "updated_at": "2021-07-09 06:50:59",
        "payout_method_type": "wallet",
        "receiver_type": "private",
        "receiver_email": "email@fasterpay.com",
        "receiver_full_name": "Firstname Lastname",
        "amounts": {
          "source_amount": "100",
          "source_currency": "EUR",
          "fee": 7.6,
          "fee_currency": "EUR",
          "converted_amount": "92.40",
          "rate": 1,
          "target_amount": "92.40",
          "target_currency": "EUR"
        }
      }
    ]
  }
}