API Reference

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

Checkout Page

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

Checkout Page Integration Parameters

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

Endpoint

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

Sample Request

<?php

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

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

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

echo $form;

Endpoint

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

Sample Request

from fasterpay.gateway import Gateway
import random

if __name__ == "__main__":
    gateway = Gateway("<your private key>", "<your public key>", 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>"

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
size
string
Pay Button size (“sm”, “md” or “lg”)
target
string
Target defines how the checkout page will be shown to the users
(“iframe”, “newWindow”, “newTab”)

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

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

Refunds

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

Headers


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

Parameters


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

Endpoint

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

Sample Request

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

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

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

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

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

Endpoint

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

Sample request

from fasterpay.gateway import Gateway

if __name__ == "__main__":

    gateway = Gateway("<your private key>", "<your public key>", 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

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

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": []
}

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