☰

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

Localized Address Fields

Retrieve the address fields required for the specified country.

Response Parameters

Field Description
country_code Country for which address formatting and requirements apply.
fields List of address components required to build the localized_address object. For each field, use the name value as the key in your request .
subdivisions List of valid values for the administrative_area field, if applicable. Use the code from each subdivision as the value in your localized_address.

Endpoint

GET https://business.fasterpay.com/api/external/address/fields/US

Sample success response

{
    "success": true,
    "data": {
        "country_code": "US",
        "fields": [
            {
                "type": "text",
                "label": "Address",
                "name": "address_line1"
            },
            {
                "type": "text",
                "label": "Postal Code",
                "name": "postal_code"
            },
            {
                "type": "text",
                "label": "City",
                "name": "locality"
            },
            {
                "type": "select",
                "label": "State",
                "name": "administrative_area",
                "level": 1
            }
        ],
        "subdivisions": [
            {
                "code": "AL",
                "name": "Alabama",
                "children": []
            },
            {
                "code": "AK",
                "name": "Alaska",
                "children": []
            },
            {
                "code": "AS",
                "name": "American Samoa",
                "children": []
            },
            {
                "code": "AZ",
                "name": "Arizona",
                "children": []
            },
            {
                "code": "AR",
                "name": "Arkansas",
                "children": []
            },
            {
                "code": "AA",
                "name": "Armed Forces (AA)",
                "children": []
            },
            {
                "code": "AE",
                "name": "Armed Forces (AE)",
                "children": []
            },
            {
                "code": "AP",
                "name": "Armed Forces (AP)",
                "children": []
            },
            {
                "code": "CA",
                "name": "California",
                "children": []
            },
            {
                "code": "CO",
                "name": "Colorado",
                "children": []
            },
            {
                "code": "CT",
                "name": "Connecticut",
                "children": []
            },
            {
                "code": "DE",
                "name": "Delaware",
                "children": []
            },
            {
                "code": "DC",
                "name": "District of Columbia",
                "children": []
            },
            {
                "code": "FL",
                "name": "Florida",
                "children": []
            },
            {
                "code": "GA",
                "name": "Georgia",
                "children": []
            },
            {
                "code": "GU",
                "name": "Guam",
                "children": []
            },
            {
                "code": "HI",
                "name": "Hawaii",
                "children": []
            },
            {
                "code": "ID",
                "name": "Idaho",
                "children": []
            },
            {
                "code": "IL",
                "name": "Illinois",
                "children": []
            },
            {
                "code": "IN",
                "name": "Indiana",
                "children": []
            },
            {
                "code": "IA",
                "name": "Iowa",
                "children": []
            },
            {
                "code": "KS",
                "name": "Kansas",
                "children": []
            },
            {
                "code": "KY",
                "name": "Kentucky",
                "children": []
            },
            {
                "code": "LA",
                "name": "Louisiana",
                "children": []
            },
            {
                "code": "ME",
                "name": "Maine",
                "children": []
            },
            {
                "code": "MH",
                "name": "Marshall Islands",
                "children": []
            },
            {
                "code": "MD",
                "name": "Maryland",
                "children": []
            },
            {
                "code": "MA",
                "name": "Massachusetts",
                "children": []
            },
            {
                "code": "MI",
                "name": "Michigan",
                "children": []
            },
            {
                "code": "FM",
                "name": "Micronesia",
                "children": []
            },
            {
                "code": "MN",
                "name": "Minnesota",
                "children": []
            },
            {
                "code": "MS",
                "name": "Mississippi",
                "children": []
            },
            {
                "code": "MO",
                "name": "Missouri",
                "children": []
            },
            {
                "code": "MT",
                "name": "Montana",
                "children": []
            },
            {
                "code": "NE",
                "name": "Nebraska",
                "children": []
            },
            {
                "code": "NV",
                "name": "Nevada",
                "children": []
            },
            {
                "code": "NH",
                "name": "New Hampshire",
                "children": []
            },
            {
                "code": "NJ",
                "name": "New Jersey",
                "children": []
            },
            {
                "code": "NM",
                "name": "New Mexico",
                "children": []
            },
            {
                "code": "NY",
                "name": "New York",
                "children": []
            },
            {
                "code": "NC",
                "name": "North Carolina",
                "children": []
            },
            {
                "code": "ND",
                "name": "North Dakota",
                "children": []
            },
            {
                "code": "MP",
                "name": "Northern Mariana Islands",
                "children": []
            },
            {
                "code": "OH",
                "name": "Ohio",
                "children": []
            },
            {
                "code": "OK",
                "name": "Oklahoma",
                "children": []
            },
            {
                "code": "OR",
                "name": "Oregon",
                "children": []
            },
            {
                "code": "PW",
                "name": "Palau",
                "children": []
            },
            {
                "code": "PA",
                "name": "Pennsylvania",
                "children": []
            },
            {
                "code": "PR",
                "name": "Puerto Rico",
                "children": []
            },
            {
                "code": "RI",
                "name": "Rhode Island",
                "children": []
            },
            {
                "code": "SC",
                "name": "South Carolina",
                "children": []
            },
            {
                "code": "SD",
                "name": "South Dakota",
                "children": []
            },
            {
                "code": "TN",
                "name": "Tennessee",
                "children": []
            },
            {
                "code": "TX",
                "name": "Texas",
                "children": []
            },
            {
                "code": "UT",
                "name": "Utah",
                "children": []
            },
            {
                "code": "VT",
                "name": "Vermont",
                "children": []
            },
            {
                "code": "VI",
                "name": "Virgin Islands",
                "children": []
            },
            {
                "code": "VA",
                "name": "Virginia",
                "children": []
            },
            {
                "code": "WA",
                "name": "Washington",
                "children": []
            },
            {
                "code": "WV",
                "name": "West Virginia",
                "children": []
            },
            {
                "code": "WI",
                "name": "Wisconsin",
                "children": []
            },
            {
                "code": "WY",
                "name": "Wyoming",
                "children": []
            }
        ]
    }
}

Create Contact

Parameters

Parameter Description
email
required if phone is not present
string		 Email
phone
required if email is not present
string		 Phone number
phone_country_code
required if phone is present
string		 Phone country code in ISO 3166-1 alpha-2 format
first_name
optional
string		 First name (maximum 90 characters)
last_name
optional
string		 First name (maximum 90 characters)
country
optional
string		 Country code in ISO 3166-1 alpha-2 format
favorite
optional
boolean		 Mark this contact as favorite

Endpoint

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

Sample request data

{
  "email": "john.smith@email.com",
  "phone": "2015550124",
  "phone_country_code": "US",
  "first_name": "John",
  "last_name": "Smith",
  "country": "US",
  "favorite": true
}

Sample success response

{
  "success": true,
  "data": {
    "id": "CT-250527-AZARCIJE",
    "email": "john.smith@email.com",
    "phone": "2015550124",
    "phone_code": "1",
    "phone_country_code": "US",
    "phone_full_number": "12015550124",
    "first_name": "John",
    "last_name": "Smith",
    "full_name": "John Smith",
    "favorite": true,
    "profile_picture": "https://example.com/profile-picture.jpg"
  }
}

Contact List

Parameters

Parameter Description
prefer_favorite
optional
boolean		 Show favorite contacts first
fasterpay_account_only
optional
boolean		 Show only contacts that have FasterPay accounts
name
optional
string		 Show contacts with first or last names containing the given keyword
email
optional
string		 Show contacts with emails starting with the given keyword
phone
optional
string		 Filter by phone number
country
optional
boolean		 Filter by country (code in ISO 3166-1 alpha-2 format)
sort_by
required if order_by is present
enum		 Sort by one of the following fields: first_name, last_name, favorite, updated_at, last_transfer_at
order_by
required if sort_by is present
enum		 Sorting order: asc (ascending), desc (descending)
page
optional
integer		 Page number to retrieve, starting from 1
per_page
optional
integer		 Number of records per page (maximum 1000)

Endpoint

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

Sample success response

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "CT-250527-AZARCIJE",
        "email": "john.smith@email.com",
        "phone": "2015550124",
        "phone_code": "1",
        "phone_country_code": "US",
        "phone_full_number": "12015550124",
        "first_name": "John",
        "last_name": "Smith",
        "full_name": "John Smith",
        "favorite": true,
        "profile_picture": "https://example.com/profile-picture.jpg"
      }
    ],
    "current_page": 1,
    "per_page": 15,
    "total": 1,
    "last_page": 1
  }
}

Contact Details

Endpoint

GET https://business.fasterpay.com/api/external/contacts/CT-250527-AZARCIJE

Sample success response

{
  "success": true,
  "data": {
    "id": "CT-250527-AZARCIJE",
    "email": "john.smith@email.com",
    "phone": "2015550124",
    "phone_code": "1",
    "phone_country_code": "US",
    "phone_full_number": "12015550124",
    "first_name": "John",
    "last_name": "Smith",
    "full_name": "John Smith",
    "favorite": true,
    "profile_picture": "https://example.com/profile-picture.jpg"
  }
}

Update Contact

Parameters

Parameter Description
email
optional
string		 Email
phone
optional
string		 Phone number
phone_country_code
required if phone is present
string		 Phone country code in ISO 3166-1 alpha-2 format
first_name
optional
string		 First name (maximum 90 characters)
last_name
optional
string		 First name (maximum 90 characters)
country
optional
string		 Country code in ISO 3166-1 alpha-2 format
favorite
optional
boolean		 Mark this contact as favorite

Endpoint

PUT https://business.fasterpay.com/api/external/contacts/CT-250527-AZARCIJE

Sample request data

{
  "email": "john.smith@email.com",
  "phone": "2015550124",
  "phone_country_code": "US",
  "first_name": "John",
  "last_name": "Smith",
  "country": "US",
  "favorite": true
}

Sample success response

{
  "success": true,
  "data": {
    "id": "CT-250527-AZARCIJE",
    "email": "john.smith@email.com",
    "phone": "2015550124",
    "phone_code": "1",
    "phone_country_code": "US",
    "phone_full_number": "12015550124",
    "first_name": "John",
    "last_name": "Smith",
    "full_name": "John Smith",
    "favorite": true,
    "profile_picture": "https://example.com/profile-picture.jpg"
  }
}

Delete Contact

Endpoint

DELETE https://business.fasterpay.com/api/external/contacts/CT-250527-AZARCIJE

Sample success response

{
  "success": true
}

E-Invoice API

E-Invoice API allows you to generate and manage electronic invoices directly through the dashboard or via API integration. You can create invoices programmatically and have them sent directly to your customers. Once an invoice is issued, you can track its status via API calls and sync invoice data with your backend for reporting or reconciliation. This enables a smoother invoicing process with minimal manual effort.

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 Invoice

Parameters

Parameter Description
invoice_template_id string or template object
Only one is required		 Provide either invoice_template_id (ID of an existing template) or template (an invoice template object). Do not use both. See Create Invoice Template for the object structure.
number
optional
string		 Unique invoice number (maximum 50 characters)
summary
optional
string		 Description (maximum 255 characters)
contact_id
required
string		 ID of an existing Contact.
currency
required
string		 Currency code in ISO-4217 format
due_date
optional
string		 Invoice due date in yyyy-mm-dd format
discount_id string or discount object
Only one is required		 Provide either discount_id (ID of an existing discount) or discount (a discount object). Do not provide both. See Create Invoice Discount for the object structure.
tax_id string or tax object
Only one is required		 Provide either tax_id (ID of an existing tax) or tax (an embedded tax object). Do not provide both. See Create Invoice Tax for the object structure.
items
required
array		 List of items/products
Item Object  
name
optional
string		 Item name (maximum 255 characters)
product_id string or product object
Only one is required		 Provide either product_id (ID of an existing product) or product (a product object). Do not provide both. See Create Invoice Product for the object structure.
deleted_at
optional
string		 Set to true to permanently delete the item.
price
required
numeric		 Unit price of the item
discount_id string or discount object
Only one is required		 Provide either discount_id (ID of an existing discount) or discount (a discount object). Do not provide both. See Create Invoice Discount for the object structure.
tax_id string or tax object
Only one is required		 Provide either tax_id (ID of an existing tax) or tax (an embedded tax object). Do not provide both. See Create Invoice Tax for the object structure.
quantity
required
integer		 Quantity (minimum: 1)
include
optional
enum		 Set to prices to show custom prices of items in the response

Endpoint

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

Sample request data

{
  "invoice_template_id": "IT-250527-AWRO",
  "tax_id": "TX-250527-2E9N",
  "discount_id": "DC-250527-WZX0",
  "currency": "USD",
  "summary": "Test description",
  "number": "invtest",
  "contact_id": "CT-250527-AZARCIJE",
  "items": [
    {
      "price": 1.5,
      "product_id": "PD-250528-L5CC",
      "tax_id": "TX-250527-2E9N",
      "discount_id": "DC-250527-WZX0",
      "quantity": 1
    }
  ]
}

Sample request data with embedded components (request must be multipart/form-data if files are provided)

{
  "template": {
    "name": "Test template",
    "address": null,
    "footer": "Test footer note",
    "colors": {
      "primary": "#05026e",
      "secondary": "#e0f5ff"
    },
    "localized_address": {
      "address_line1": "1 Market St",
      "locality": "San Francisco",
      "administrative_area": "CA",
      "postal_code": "94105"
    },
    "country_code": "US",
    "logo": "<attached logo file>"
  },
  "tax": {
    "name": "Test tax",
    "type": "flat",
    "value": 0.1,
    "description": "Test tax description"
  },
  "discount": {
    "name": "Test discount",
    "type": "flat",
    "value": 0.1,
    "currency": "USD",
    "description": "Test discount description"
  },
  "currency": "USD",
  "summary": "Test description",
  "number": "invtest",
  "contact_id": "CT-250527-AZARCIJE",
  "items": [
    {
      "price": 1.5,
      "product": {
        "sku": "testprod",
        "type": "digital",
        "name": "Test product",
        "description": "Test product description",
        "image": "<attached image file>",
        "prices": [
          {
            "price": "1.50",
            "currency": "USD"
          }
        ]
      },
      "tax": {
        "name": "Test tax",
        "type": "flat",
        "value": 0.1,
        "description": "Test tax description"
      },
      "discount": {
        "name": "Test discount",
        "type": "flat",
        "value": 0.1,
        "currency": "USD",
        "description": "Test discount description"
      },
      "quantity": 1
    }
  ]
}

Sample success response

{
  "success": true,
  "data": {
    "id": "FPBIV-250615-NNUA",
    "status": "draft",
    "summary": "Test description",
    "currency": "USD",
    "due_date": "2025-06-22T00:00:00.000000Z",
    "contact_id": "CT-250527-AZARCIJE",
    "template": {
      "id": "IT-250615-Q3CN",
      "name": "Test template",
      "address": null,
      "footer": "Test footer note",
      "colors": {
        "primary": "#05026e",
        "secondary": "#e0f5ff"
      },
      "localized_address": {
        "address_line1": "1 Market St",
        "locality": "San Francisco",
        "administrative_area": "CA",
        "postal_code": "94105"
      },
      "country_code": "US",
      "logo_url": "https://example.com/logo.jpg",
      "full_address": "1 Market St\nSan Francisco CA 94105\nUnited States"
    },
    "tax": {
      "id": "TX-250527-2E9N",
      "name": "Test tax",
      "type": "flat",
      "value": 0.1,
      "description": "Test tax description"
    },
    "discount": {
      "id": "DC-250527-WZX0",
      "name": "Test discount",
      "type": "flat",
      "value": 0.1,
      "currency": "USD",
      "description": "Test discount description"
    },
    "items": [
      {
        "name": "Test product",
        "price": 1.5,
        "quantity": 1,
        "currency": "USD",
        "id": "IVI-250615-SKTN",
        "product": {
          "id": "PD-250528-L5CC",
          "sku": "testprod",
          "type": "digital",
          "name": "Test product",
          "description": "Test product description",
          "image_url": "https://example.com/image.jpg",
          "prices": [
            {
              "price": 1.50,
              "currency": "USD"
            }
          ]
        },
        "tax": {
          "id": "TX-250527-2E9N",
          "name": "Test tax",
          "type": "flat",
          "value": 0.1,
          "description": "Test tax description"
        },
        "discount": {
          "id": "DC-250527-WZX0",
          "name": "Test discount",
          "type": "flat",
          "value": 0.1,
          "currency": "USD",
          "description": "Test tax description"
        }
      }
    ],
    "created_at": "2025-06-15T07:58:21.000000Z"
  }
}

Invoice List

Retrieves a list of all invoices available in the system, including their configuration details.

Parameters

Parameter Description
include
string		 Comma separated list of related components to be shown, which can be the following values: items, items.product.prices
page
optional
integer		 Page number to retrieve, starting from 1
per_page
optional
integer		 Number of records per page (maximum 1000)
filter
object		  
Filter Object  
status
enum		 Filter by invoice status. Refer to Invoice Statuses
currency
string		 Filter by currency (code in ISO-4217 format)
created_at
string		 Filter invoices created within the given date range (comma separated values of dates in YYYY-MM-DD format)
due_date
string		 Filter invoices with due dates within the given date range (comma separated values of dates in YYYY-MM-DD format)
grand_total
string		 Filter invoices with grand total amount within the given range (comma separated values of amounts)
search
string		 Search invoices by the given keyword

Endpoint

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

Sample query string data

?include=items.product.prices

Sample success response

{
  "success": true,
  "data": {
    "total": 1,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "data": [
      {
        "id": "FPBIV-250615-NNUA",
        "status": "draft",
        "summary": "Test description",
        "currency": "USD",
        "due_date": "2025-06-22T00:00:00.000000Z",
        "contact_id": "CT-250527-AZARCIJE",
        "template": {
          "id": "IT-250615-Q3CN",
          "name": "Test template",
          "address": null,
          "footer": "Test footer note",
          "colors": {
            "primary": "#05026e",
            "secondary": "#e0f5ff"
          },
          "localized_address": {
            "address_line1": "1 Market St",
            "locality": "San Francisco",
            "administrative_area": "CA",
            "postal_code": "94105"
          },
          "country_code": "US",
          "logo_url": "https://example.com/logo.jpg",
          "full_address": "1 Market St\nSan Francisco CA 94105\nUnited States"
        },
        "tax": {
          "id": "TX-250527-2E9N",
          "name": "Test tax",
          "type": "flat",
          "value": 0.1,
          "description": "Test tax description"
        },
        "discount": {
          "id": "DC-250527-WZX0",
          "name": "Test discount",
          "type": "flat",
          "value": 0.1,
          "currency": "USD",
          "description": "Test discount description"
        },
        "items": [
          {
            "name": "Test product",
            "price": 1.5,
            "quantity": 1,
            "currency": "USD",
            "id": "IVI-250615-SKTN",
            "product": {
              "id": "PD-250528-L5CC",
              "sku": "testprod",
              "type": "digital",
              "name": "Test product",
              "description": "Test product description",
              "image_url": "https://example.com/image.jpg",
              "prices": [
                {
                  "price": 1.50,
                  "currency": "USD"
                }
              ]
            },
            "tax": {
              "id": "TX-250527-2E9N",
              "name": "Test tax",
              "type": "flat",
              "value": 0.1,
              "description": "Test tax description"
            },
            "discount": {
              "id": "DC-250527-WZX0",
              "name": "Test discount",
              "type": "flat",
              "value": 0.1,
              "currency": "USD",
              "description": "Test tax description"
            }
          }
        ],
        "created_at": "2025-06-15T07:58:21.000000Z"
      }
    ]
  }
}

Invoice Details

Retrieves the details of a specific invoice by its ID. Returns full invoice data including status, items, amounts, and contact information.

Parameters

Parameter Description
include
enum		 Set to prices to show custom prices of items in the response

Endpoint

GET https://business.fasterpay.com/api/external/invoices/FPBIV-250615-NNUA

Sample query string data

?include=prices

Sample success response

{
  "success": true,
  "data": {
    "id": "FPBIV-250615-NNUA",
    "status": "draft",
    "summary": "Test description",
    "currency": "USD",
    "due_date": "2025-06-22T00:00:00.000000Z",
    "contact_id": "CT-250527-AZARCIJE",
    "template": {
      "id": "IT-250615-Q3CN",
      "name": "Test template",
      "address": null,
      "footer": "Test footer note",
      "colors": {
        "primary": "#05026e",
        "secondary": "#e0f5ff"
      },
      "localized_address": {
        "address_line1": "1 Market St",
        "locality": "San Francisco",
        "administrative_area": "CA",
        "postal_code": "94105"
      },
      "country_code": "US",
      "logo_url": "https://example.com/logo.jpg",
      "full_address": "1 Market St\nSan Francisco CA 94105\nUnited States"
    },
    "tax": {
      "id": "TX-250527-2E9N",
      "name": "Test tax",
      "type": "flat",
      "value": 0.1,
      "description": "Test tax description"
    },
    "discount": {
      "id": "DC-250527-WZX0",
      "name": "Test discount",
      "type": "flat",
      "value": 0.1,
      "currency": "USD",
      "description": "Test discount description"
    },
    "items": [
      {
        "name": "Test product",
        "price": 1.5,
        "quantity": 1,
        "currency": "USD",
        "id": "IVI-250615-SKTN",
        "product": {
          "id": "PD-250528-L5CC",
          "sku": "testprod",
          "type": "digital",
          "name": "Test product",
          "description": "Test product description",
          "image_url": "https://example.com/image.jpg",
          "prices": [
            {
              "price": 1.50,
              "currency": "USD"
            }
          ]
        },
        "tax": {
          "id": "TX-250527-2E9N",
          "name": "Test tax",
          "type": "flat",
          "value": 0.1,
          "description": "Test tax description"
        },
        "discount": {
          "id": "DC-250527-WZX0",
          "name": "Test discount",
          "type": "flat",
          "value": 0.1,
          "currency": "USD",
          "description": "Test tax description"
        }
      }
    ],
    "created_at": "2025-06-15T07:58:21.000000Z"
  }
}

Update Invoice Details

Parameters

Parameter Description
invoice_template_id
optional
string		 Invoice template ID
template
optional
object		 Embedded template. Refer to Create Invoice Template for this component’s parameters
tax_id
optional
string		 Tax ID
tax
optional
object		 Embedded tax. Refer to Create Invoice Tax for this component’s parameters
discount_id
optional
string		 Discount ID
discount
optional
object		 Embedded discount. Refer to Create Invoice Discount for this component’s parameters
currency
optional
string		 Currency code in ISO-4217 format
summary
optional
string		 Description (maximum 255 characters)
number
optional
string		 Unique invoice number (maximum 50 characters)
contact_id
optional
string		 Contact ID
due_date
optional
string		 Due date (format: YYYY-MM-DD)
items
optional
array		 List of items
Item Object  
id
required if the item’s deleted_at is present
string		 Item ID. If this is provided the item will be updated/deleted
deleted_at
optional
any		 If this is provided the item will be deleted
name
optional
string		 Item name (maximum 255 characters)
price
required if the item’s deleted_at is not present
numeric		 Item price
product_id
required if the item’s product, name and deleted_at are not present
string		 Product ID
product
optional
object		 Embedded product. Refer to Create Invoice Product for this component’s parameters
tax_id
optional
string		 Tax ID
tax
optional
object		 Embedded tax. Refer to Create Invoice Tax for this component’s parameters
discount_id
optional
string		 Discount ID
discount
optional
object		 Embedded discount. Refer to Create Invoice Discount for this component’s parameters
quantity
required if the item’s deleted_at is not present
integer		 Quantity (minimum 1)
include
optional
enum		 Set to prices to show custom prices of items in the response

Endpoint

PUT (POST if files are provided) https://business.fasterpay.com/api/external/invoices/FPBIV-250615-NNUA

Sample request data

{
  "invoice_template_id": "IT-250527-AWRO",
  "tax_id": "TX-250527-2E9N",
  "discount_id": "DC-250527-WZX0",
  "currency": "USD",
  "summary": "Test description",
  "number": "invtest",
  "contact_id": "CT-250527-AZARCIJE",
  "items": [
    {
      "price": 1.5,
      "product_id": "PD-250528-L5CC",
      "tax_id": "TX-250527-2E9N",
      "discount_id": "DC-250527-WZX0",
      "quantity": 1
    }
  ]
}

Sample request data with embedded components (request must be multipart/form-data if files are provided)

{
  "template": {
    "name": "Test template",
    "address": null,
    "footer": "Test footer note",
    "colors": {
      "primary": "#05026e",
      "secondary": "#e0f5ff"
    },
    "localized_address": {
      "address_line1": "1 Market St",
      "locality": "San Francisco",
      "administrative_area": "CA",
      "postal_code": "94105"
    },
    "country_code": "US",
    "logo": "<attached logo file>"
  },
  "tax": {
    "name": "Test tax",
    "type": "flat",
    "value": 0.1,
    "description": "Test tax description"
  },
  "discount": {
    "name": "Test discount",
    "type": "flat",
    "value": 0.1,
    "currency": "USD",
    "description": "Test discount description"
  },
  "currency": "USD",
  "summary": "Test description",
  "number": "invtest",
  "contact_id": "CT-250527-AZARCIJE",
  "due_date": "2025-06-29T00:00:00.000000Z",
  "items": [
    {
      "price": 1.5,
      "product": {
        "sku": "testprod",
        "type": "digital",
        "name": "Test product",
        "description": "Test product description",
        "image": "<attached image file>",
        "prices": [
          {
            "price": "1.50",
            "currency": "USD"
          }
        ]
      },
      "tax": {
        "name": "Test tax",
        "type": "flat",
        "value": 0.1,
        "description": "Test tax description"
      },
      "discount": {
        "name": "Test discount",
        "type": "flat",
        "value": 0.1,
        "currency": "USD",
        "description": "Test discount description"
      },
      "quantity": 1
    }
  ]
}

Sample success response

{
  "success": true,
  "data": {
    "id": "FPBIV-250615-NNUA",
    "status": "draft",
    "summary": "Test description",
    "currency": "USD",
    "due_date": "2025-06-29T00:00:00.000000Z",
    "contact_id": "CT-250527-AZARCIJE",
    "template": {
      "id": "IT-250615-Q3CN",
      "name": "Test template",
      "address": null,
      "footer": "Test footer note",
      "colors": {
        "primary": "#05026e",
        "secondary": "#e0f5ff"
      },
      "localized_address": {
        "address_line1": "1 Market St",
        "locality": "San Francisco",
        "administrative_area": "CA",
        "postal_code": "94105"
      },
      "country_code": "US",
      "logo_url": "https://example.com/logo.jpg",
      "full_address": "1 Market St\nSan Francisco CA 94105\nUnited States"
    },
    "tax": {
      "id": "TX-250527-2E9N",
      "name": "Test tax",
      "type": "flat",
      "value": 0.1,
      "description": "Test tax description"
    },
    "discount": {
      "id": "DC-250527-WZX0",
      "name": "Test discount",
      "type": "flat",
      "value": 0.1,
      "currency": "USD",
      "description": "Test discount description"
    },
    "items": [
      {
        "name": "Test product",
        "price": 1.5,
        "quantity": 1,
        "currency": "USD",
        "id": "IVI-250615-SKTN",
        "product": {
          "id": "PD-250528-L5CC",
          "sku": "testprod",
          "type": "digital",
          "name": "Test product",
          "description": "Test product description",
          "image_url": "https://example.com/image.jpg",
          "prices": [
            {
              "price": 1.50,
              "currency": "USD"
            }
          ]
        },
        "tax": {
          "id": "TX-250527-2E9N",
          "name": "Test tax",
          "type": "flat",
          "value": 0.1,
          "description": "Test tax description"
        },
        "discount": {
          "id": "DC-250527-WZX0",
          "name": "Test discount",
          "type": "flat",
          "value": 0.1,
          "currency": "USD",
          "description": "Test tax description"
        }
      }
    ],
    "created_at": "2025-06-15T07:58:21.000000Z"
  }
}

Update Invoice Status

Parameters

Parameter Description
status
required
enum		 Specify the new status for the invoice. Allowed values are:
- void
- uncollectible

Endpoint

PUT https://business.fasterpay.com/api/external/invoices/FPBIV-250615-NNUA/status

Sample request data

{
  "status": "finalized"
}

Sample success response

{
  "success": true,
  "data": {
    "id": "FPBIV-250615-NNUA",
    "status": "finalized",
    "summary": "Test description",
    "currency": "USD",
    "due_date": "2025-06-22T00:00:00.000000Z",
    "contact_id": "CT-250527-AZARCIJE",
    "template": {
      "id": "IT-250615-Q3CN",
      "name": "Test template",
      "address": null,
      "footer": "Test footer note",
      "colors": {
        "primary": "#05026e",
        "secondary": "#e0f5ff"
      },
      "localized_address": {
        "address_line1": "1 Market St",
        "locality": "San Francisco",
        "administrative_area": "CA",
        "postal_code": "94105"
      },
      "country_code": "US",
      "logo_url": "https://example.com/logo.jpg",
      "full_address": "1 Market St\nSan Francisco CA 94105\nUnited States"
    },
    "tax": {
      "id": "TX-250527-2E9N",
      "name": "Test tax",
      "type": "flat",
      "value": 0.1,
      "description": "Test tax description"
    },
    "discount": {
      "id": "DC-250527-WZX0",
      "name": "Test discount",
      "type": "flat",
      "value": 0.1,
      "currency": "USD",
      "description": "Test discount description"
    },
    "items": [
      {
        "name": "Test product",
        "price": 1.5,
        "quantity": 1,
        "currency": "USD",
        "id": "IVI-250615-SKTN",
        "product": {
          "id": "PD-250528-L5CC",
          "sku": "testprod",
          "type": "digital",
          "name": "Test product",
          "description": "Test product description",
          "image_url": "https://example.com/image.jpg",
          "prices": [
            {
              "price": 1.50,
              "currency": "USD"
            }
          ]
        },
        "tax": {
          "id": "TX-250527-2E9N",
          "name": "Test tax",
          "type": "flat",
          "value": 0.1,
          "description": "Test tax description"
        },
        "discount": {
          "id": "DC-250527-WZX0",
          "name": "Test discount",
          "type": "flat",
          "value": 0.1,
          "currency": "USD",
          "description": "Test tax description"
        }
      }
    ],
    "created_at": "2025-06-15T07:58:21.000000Z"
  }
}

Preview Invoice

Generates an HTML preview of the invoice’s PDF version. This allows you to review the invoice layout and content exactly as it will appear in the final PDF before sending or printing.

Endpoint

GET https://business.fasterpay.com/api/external/invoices/FPBIV-250615-NNUA/pdf

Send Invoice

Sends the invoice to the customer’s email address with invoice details.

Parameters

Parameter Description
test
optional
boolean		 Send a test invoice email to the merchant’s email address

Endpoint

POST https://business.fasterpay.com/api/external/invoices/FPBIV-250615-NNUA/send

Sample success response

{
  "success": true,
  "data": {
    "id": "FPBIV-250615-NNUA",
    "status": "sent",
    "summary": "Test description",
    "currency": "USD",
    "due_date": "2025-06-22T00:00:00.000000Z",
    "contact_id": "CT-250527-AZARCIJE",
    "template": {
      "id": "IT-250615-Q3CN",
      "name": "Test template",
      "address": null,
      "footer": "Test footer note",
      "colors": {
        "primary": "#05026e",
        "secondary": "#e0f5ff"
      },
      "localized_address": {
        "address_line1": "1 Market St",
        "locality": "San Francisco",
        "administrative_area": "CA",
        "postal_code": "94105"
      },
      "country_code": "US",
      "logo_url": "https://example.com/logo.jpg",
      "full_address": "1 Market St\nSan Francisco CA 94105\nUnited States"
    },
    "tax": {
      "id": "TX-250527-2E9N",
      "name": "Test tax",
      "type": "flat",
      "value": 0.1,
      "description": "Test tax description"
    },
    "discount": {
      "id": "DC-250527-WZX0",
      "name": "Test discount",
      "type": "flat",
      "value": 0.1,
      "currency": "USD",
      "description": "Test discount description"
    },
    "items": [
      {
        "name": "Test product",
        "price": 1.5,
        "quantity": 1,
        "currency": "USD",
        "id": "IVI-250615-SKTN",
        "product": {
          "id": "PD-250528-L5CC",
          "sku": "testprod",
          "type": "digital",
          "name": "Test product",
          "description": "Test product description",
          "image_url": "https://example.com/image.jpg",
          "prices": [
            {
              "price": 1.50,
              "currency": "USD"
            }
          ]
        },
        "tax": {
          "id": "TX-250527-2E9N",
          "name": "Test tax",
          "type": "flat",
          "value": 0.1,
          "description": "Test tax description"
        },
        "discount": {
          "id": "DC-250527-WZX0",
          "name": "Test discount",
          "type": "flat",
          "value": 0.1,
          "currency": "USD",
          "description": "Test tax description"
        }
      }
    ],
    "created_at": "2025-06-15T07:58:21.000000Z"
  }
}

Invoice Pingbacks

A pingback is sent automatically when the invoice status changes, indicating the updated status.

Parameters

Parameter Description
event invoice.status.updated
pingback_ts Unix timestamp of the time when the pingback was sent
invoice  
Invoice Object  
id Invoice ID
status Invoice status. Refer to Invoice Statuses

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.

More information can be found in the documentation here

Pingback sample

{
  "event": "invoice.status.updated",
  "invoice": {
    "status": "void",
    "id": "FPBIV-250616-3UHJ"
  }
}

Invoice Statuses

Possible Values

Parameter Description
draft The invoice is created.
sent The invoice is sent.
paid Invoice has been paid by contact.
overdue Payment is past due but still accepted.
void Invoice voided by merchant; only if unpaid and not expired.
uncollectible Invoice marked as uncollectible due to non-payment.
expired Invoice expired 30 days after overdue; payment not accepted, new invoice required.
refunded Payment for the invoice has been refunded to the contact.

Invoices with the statuses paid, void, uncollectible, expired, or refunded cannot be updated using the Update Invoice Status API, and no emails can be sent for them.

Create Invoice Template

Parameters

Parameter Description
name
required
string		 Template name (maximum 191 characters)
country_code
required
string		 Country code in ISO 3166-1 alpha-2 format
footer
optional
string		 Footer note
logo
optional
file		 Template logo (maximum 1 MB). Allowed extensions: .jpg, .jpeg, .png
address string or localized_address object
Only one is required		 Provide either address (generic address format) or localized_address (country-specific format). Do not use both. To determine if a country supports localized_address, query Address Fields. If the country is not supported, use the address parameter instead.
colors
required
object		 Color configurations
Colors Object  
primary
required
string		 Brand color (Hex code)
secondary
required
string		 Second color (Hex code)

Endpoint

POST https://business.fasterpay.com/api/external/invoices/templates

Sample request data (request must be multipart/form-data if logo is provided)

{
  "name": "Test template",
  "footer": "Test footer note",
  "colors": {
    "primary": "#05026e",
    "secondary": "#e0f5ff"
  },
  "localized_address": {
    "address_line1": "1 Market St",
    "locality": "San Francisco",
    "administrative_area": "CA",
    "postal_code": "94105"
  },
  "country_code": "US",
  "logo": "<attached logo file>"
}

Sample success response

{
  "success": true,
  "data": {
    "id": "IT-250615-Q3CN",
    "name": "Test template",
    "address": null,
    "footer": "Test footer note",
    "colors": {
      "primary": "#05026e",
      "secondary": "#e0f5ff"
    },
    "localized_address": {
      "address_line1": "1 Market St",
      "locality": "San Francisco",
      "administrative_area": "CA",
      "postal_code": "94105"
    },
    "country_code": "US",
    "logo_url": "https://example.com/logo.jpg",
    "full_address": "1 Market St\nSan Francisco CA 94105\nUnited States"
  }
}

Invoice Template List

Retrieves a list of all invoice templates available in the system, including all their configuration details.

Parameters

Parameter Description
page
optional
integer		 Page number to retrieve, starting from 1
per_page
optional
integer		 Number of records per page (maximum 1000)
filter
object		  
Filter Object  
name
string		 Filter by template name

Endpoint

GET https://business.fasterpay.com/api/external/invoices/templates

Sample success response

{
  "success": true,
  "data": {
    "total": 1,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "data": [
      {
        "id": "IT-250615-Q3CN",
        "name": "Test template",
        "address": null,
        "footer": "Test footer note",
        "colors": {
          "primary": "#05026e",
          "secondary": "#e0f5ff"
        },
        "localized_address": {
          "address_line1": "1 Market St",
          "locality": "San Francisco",
          "administrative_area": "CA",
          "postal_code": "94105"
        },
        "country_code": "US",
        "logo_url": "https://example.com/logo.jpg",
        "full_address": "1 Market St\nSan Francisco CA 94105\nUnited States"
      }
    ]
  }
}

Invoice Template Details

Retrieves an existing invoice template by ID and returns its full configuration details.

Endpoint

GET https://business.fasterpay.com/api/external/invoices/templates/IT-250615-Q3CN

Sample success response

{
  "success": true,
  "data": {
    "id": "IT-250615-Q3CN",
    "name": "Test template",
    "address": null,
    "footer": "Test footer note",
    "colors": {
      "primary": "#05026e",
      "secondary": "#e0f5ff"
    },
    "localized_address": {
      "address_line1": "1 Market St",
      "locality": "San Francisco",
      "administrative_area": "CA",
      "postal_code": "94105"
    },
    "country_code": "US",
    "logo_url": "https://example.com/logo.jpg",
    "full_address": "1 Market St\nSan Francisco CA 94105\nUnited States"
  }
}

Update Invoice Template

Parameters

Parameter Description
name
optional
string		 Template name (maximum 191 characters)
address
optional
string		 Address (maximum 191 characters)
country_code
optional
string		 Country code in ISO 3166-1 alpha-2 format
footer
optional
string		 Footer note
logo
optional
file		 Template logo (maximum 1 MB). Allowed extensions: .jpg, .jpeg, .png
localized_address
optional
object		 Address in localized format
colors
optional
object		 Color configurations
Localized Address Object  
address_line1
required
string		 Address line
locality
optional
string		 City
administrative_area
optional
string		 Administrative division (state, province, land, oblast, region, .etc)
postal_code
optional
string		 Postal code
Colors Object  
primary
optional
string		 Brand color (Hex code)
secondary
optional
string		 Second color (Hex code)

Endpoint

PUT (POST if logo is provided) https://business.fasterpay.com/api/external/invoices/templates/IT-250615-Q3CN

Sample request data (request must be multipart/form-data if logo is provided)

{
  "name": "Test template",
  "address": null,
  "footer": "Test footer note",
  "colors": {
    "primary": "#05026e",
    "secondary": "#e0f5ff"
  },
  "localized_address": {
    "address_line1": "1 Market St",
    "locality": "San Francisco",
    "administrative_area": "CA",
    "postal_code": "94105"
  },
  "country_code": "US",
  "logo": "<attached logo file>",
  "_method": "PUT"
}

Sample success response

{
  "success": true,
  "data": {
    "id": "IT-250615-Q3CN",
    "name": "Test template",
    "address": null,
    "footer": "Test footer note",
    "colors": {
      "primary": "#05026e",
      "secondary": "#e0f5ff"
    },
    "localized_address": {
      "address_line1": "1 Market St",
      "locality": "San Francisco",
      "administrative_area": "CA",
      "postal_code": "94105"
    },
    "country_code": "US",
    "logo_url": "https://example.com/logo.jpg",
    "full_address": "1 Market St\nSan Francisco CA 94105\nUnited States"
  }
}

Delete Invoice Template

Use this endpoint to permanently delete an existing invoice template.

Endpoint

DELETE https://business.fasterpay.com/api/external/invoices/templates/IT-250615-Q3CN

Sample success response

{
  "success": true
}

Create Invoice Product

Parameters

Parameter Description
name
required
string		 Product name (maximum 191 characters)
sku
optional
string		 Unique SKU (maximum 50 characters)
type
required
enum		 Product type, which can be one of the following values: physical, digital
description
optional
string		 Description
image
optional
file		 Product image (maximum 1 MB)
prices
optional
array		 Custom product prices in different currencies
Price Object  
price
required
numeric		 Price amount
currency
required
string		 Currency code in ISO-4217 format

Endpoint

POST https://business.fasterpay.com/api/external/invoices/products

Sample request data (request must be multipart/form-data if image is provided)

{
  "sku": "testprod",
  "type": "digital",
  "name": "Test product",
  "description": "Test product description",
  "image": "<attached image file>",
  "prices": [
    {
      "price": 1.50,
      "currency": "USD"
    }
  ]
}

Sample success response

{
  "success": true,
  "data": {
    "id": "PD-250528-L5CC",
    "sku": "testprod",
    "type": "digital",
    "name": "Test product",
    "description": "Test product description",
    "image_url": "https://example.com/image.jpg",
    "prices": [
      {
        "price": "1.50",
        "currency": "USD"
      }
    ]
  }
}

Invoice Product List

Retrieves a list of all products available in the system, including all their configuration details.

Parameters

Parameter Description
include
string		 Related component to be shown, which can be the following value: prices
page
optional
integer		 Page number to retrieve, starting from 1
per_page
optional
integer		 Number of records per page (maximum 1000)
filter
object		  
Filter Object  
name
string		 Filter by name
type
string		 Filter by type, which can be one of the following values: physical, digital
sku
string		 Filter by SKU
prices
object		  
Prices Object  
prices.currency
string		 Show prices in given currency (code in ISO-4217 format)

Endpoint

GET https://business.fasterpay.com/api/external/invoices/products

Sample query string data

?include=prices

Sample success response

{
  "success": true,
  "data": {
    "total": 1,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "data": [
      {
        "id": "PD-250528-L5CC",
        "sku": "testprod",
        "type": "digital",
        "name": "Test product",
        "description": "Test product description",
        "image_url": "https://example.com/image.jpg",
        "prices": [
          {
            "price": "1.50",
            "currency": "USD"
          }
        ]
      }
    ]
  }
}

Invoice Product Details

Retrieves an existing invoice product by ID and returns its full configuration details.

Endpoint

GET https://business.fasterpay.com/api/external/invoices/products/PD-250528-L5CC

Sample success response

{
  "success": true,
  "data": {
    "id": "PD-250528-L5CC",
    "sku": "testprod",
    "type": "digital",
    "name": "Test product",
    "description": "Test product description",
    "image_url": "https://example.com/image.jpg",
    "prices": [
      {
        "price": "1.50",
        "currency": "USD"
      }
    ]
  }
}

Update Invoice Product

Parameters

Parameter Description
name
optional
string		 Product name (maximum 191 characters)
sku
optional
string		 Unique SKU (maximum 50 characters)
type
optional
enum		 Product type, which can be one of the following values: physical, digital
description
optional
string		 Description
image
optional
file		 Product image (maximum 1 MB)
prices
optional
array		 Custom product prices in different currencies
_method
conditional
string		 Required only when using multipart/form-data. In this case, send the request as POST and set _method=PUT in the body to simulate a PUT request.
Price Object  
price
required
numeric		 Price amount
currency
required
string		 Currency code in ISO-4217 format

Endpoint

PUT (POST if image is provided) https://business.fasterpay.com/api/external/invoices/products/PD-250528-L5CC

Sample request data (request must be multipart/form-data if image is provided)

{
  "sku": "testprod",
  "type": "digital",
  "name": "Test product",
  "description": "Test product description",
  "image": "<attached image file>",
  "prices": [
    {
      "price": 1.50,
      "currency": "USD"
    }
  ]
}

Sample success response

{
  "success": true,
  "data": {
    "id": "PD-250528-L5CC",
    "sku": "testprod",
    "type": "digital",
    "name": "Test product",
    "description": "Test product description",
    "image_url": "https://example.com/image.jpg",
    "prices": [
      {
        "price": "1.50",
        "currency": "USD"
      }
    ]
  }
}

Delete Invoice Product

Use this endpoint to permanently delete an existing invoice product.

Endpoint

DELETE https://business.fasterpay.com/api/external/invoices/products/PD-250528-L5CC

Sample success response

{
  "success": true
}

Delete Invoice Product Price

Use this endpoint to permanently delete a specific price associated with an invoice product.

Endpoint

DELETE https://business.fasterpay.com/api/external/invoices/products/PD-250625-AXJR/prices/USD

Sample success response

{
    "success": true,
    "data": {
        "id": "PD-250625-AXJR",
        "sku": null,
        "type": "digital",
        "name": "Test product",
        "description": "Test prod des",
        "image_url": null,
        "prices": [
            {
                "price": "1.00",
                "currency": "EUR"
            }
        ]
    }
}

Create Invoice Tax

Tax can be applied at the invoice level, product item level, or both. You can either reference a existing discount using tax_id or define one inline using the tax object.

Parameters

Parameter Description
name
required
string		 Tax name (maximum 191 characters)
value
required
numeric		 Tax value (minimum 0.01, maximum 1000)
description
optional
string		 Description (maximum 191 characters)
deleted_at
optional
string		 Set to true to permanently delete the item.

Endpoint

POST https://business.fasterpay.com/api/external/invoices/taxes

Sample request data

{
  "name": "Test tax",
  "type": "flat",
  "value": 0.1,
  "description": "Test tax description"
}

Sample success response

{
  "success": true,
  "data": {
    "id": "TX-250527-2E9N",
    "name": "Test tax",
    "type": "flat",
    "value": 0.1,
    "description": "Test tax description"
  }
}

Invoice Tax List

Retrieves a list of all discounts available in the system, including their configuration details such as name, type, active status, and currency.

Parameters

Parameter Description
page
optional
integer		 Page number to retrieve, starting from 1
per_page
optional
integer		 Number of records per page (maximum 1000)
filter
object		  
Filter Object  
name
string		 Filter by name
type
string		 Filter by type
active
boolean		 Show only active taxes

Endpoint

GET https://business.fasterpay.com/api/external/invoices/taxes

Sample success response

{
  "success": true,
  "data": {
    "total": 1,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "data": [
      {
        "id": "TX-250527-2E9N",
        "name": "Test tax",
        "type": "flat",
        "value": 0.1,
        "description": "Test tax description"
      }
    ]
  }
}

Invoice Tax Details

Retrieves an existing Tax by ID and returns its full configuration details.

Endpoint

GET https://business.fasterpay.com/api/external/invoices/taxes/TX-250527-2E9N

Sample success response

{
  "success": true,
  "data": {
    "id": "TX-250527-2E9N",
    "name": "Test tax",
    "type": "flat",
    "value": 0.1,
    "description": "Test tax description"
  }
}

Update Invoice Tax

Updates an existing tax by ID. Allows changes to name, type, value, and descrption.

Parameters

Parameter Description
name
required
string		 Tax name (maximum 191 characters)
value
required
numeric		 Tax Percentage to apply (minimum 0.01, maximum 100)
description
optional
string		 Description (maximum 191 characters)

Endpoint

PUT https://business.fasterpay.com/api/external/invoices/taxes/TX-250527-2E9N

Sample request data

{
  "name": "Test tax",
  "value": 0.1,
  "description": "Test tax description"
}

Sample success response

{
  "success": true,
  "data": {
    "id": "TX-250527-2E9N",
    "name": "Test tax",
    "type": "percentage",
    "value": 0.1,
    "description": "Test tax description"
  }
}

Delete Invoice Tax

Use this endpoint to permanently delete an existing tax.

Endpoint

DELETE https://business.fasterpay.com/api/external/invoices/taxes/TX-250527-2E9N

Sample success response

{
  "success": true
}

Create Invoice Discount

Discounts can be applied at the invoice level, product item level, or both. You can either reference a existing discount using discount_id or define one inline using the discount object.

Parameters

Parameter Description
name
required
string		 Discount name (maximum 191 characters)
type
required
enum		 Discount type, which can be one of the following values: flat, percentage
value
required
numeric		 Discount value (minimum: 0.01, maximum: 1000)
currency
required if type=flat
string		 Currency code in ISO-4217 format
description
optional
string		 Description (maximum 191 characters)

Endpoint

POST https://business.fasterpay.com/api/external/invoices/discounts

Sample request data

{
  "name": "Test discount",
  "type": "flat",
  "value": 0.1,
  "currency": "USD",
  "description": "Test discount description"
}

Sample success response

{
  "success": true,
  "data": {
    "id": "DC-250527-WZX0",
    "name": "Test discount",
    "type": "flat",
    "value": 0.1,
    "currency": "USD",
    "description": "Test discount description"
  }
}

Invoice Discount List

Retrieves a list of all discounts available in the system, including their configuration details such as name, type, active status, and currency.

Parameters

Parameter Description
page
optional
integer		 Page number to retrieve, starting from 1
per_page
optional
integer		 Number of records per page (maximum 1000)
filter
object		  
Filter Object  
name
string		 Filter by name
type
string		 Filter by type
active
boolean		 Show only active discounts
currency
string		 Show discounts by the given currency (code in ISO-4217 format) or by percentage

Endpoint

GET https://business.fasterpay.com/api/external/invoices/discounts

Sample success response

{
  "success": true,
  "data": {
    "total": 1,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 1,
    "data": [
      {
        "id": "DC-250527-WZX0",
        "name": "Test discount",
        "type": "flat",
        "value": 0.1,
        "currency": "USD",
        "description": "Test discount description"
      }
    ]
  }
}

Invoice Discount Details

Retrieves an existing discount by ID and returns its full configuration details.

Endpoint

GET https://business.fasterpay.com/api/external/invoices/discounts/DC-250527-WZX0

Sample success response

{
  "success": true,
  "data": {
    "id": "DC-250527-WZX0",
    "name": "Test discount",
    "type": "flat",
    "value": 0.1,
    "currency": "USD",
    "description": "Test discount description"
  }
}

Update Invoice Discount

Updates an existing discount by ID. Allows changes to name, type, value, currency and descrption.

Parameters

Parameter Description
name
optional
string		 Discount name (maximum 191 characters)
type
optional
enum		 Discount type, which can be one of the following values: flat, percentage
value
optional
numeric		 Discount value (minimum 0.01, maximum 1000)
currency
required if type=flat
string		 Currency code in ISO-4217 format
description
optional
string		 Description (maximum 191 characters)

Endpoint

PUT https://business.fasterpay.com/api/external/invoices/discounts/DC-250527-WZX0

Sample request data

{
  "name": "Test discount",
  "type": "flat",
  "value": 0.1,
  "currency": "USD",
  "description": "Test discount description"
}

Sample success response

{
  "success": true,
  "data": {
    "id": "DC-250527-WZX0",
    "name": "Test discount",
    "type": "flat",
    "value": 0.1,
    "currency": "USD",
    "description": "Test discount description"
  }
}

Delete Invoice Discount

Use this endpoint to permanently delete an existing discount.

Endpoint

DELETE https://business.fasterpay.com/api/external/invoices/discounts/DC-250527-WZX0

Sample success response

{
  "success": true
}