Pre-authorise a Payment

Pre-authorisation allows you to reserve funds on a customer's card for a period of time, before capturing the payment at a later date. This is available for both embedded (ecommerce) and payment links.

1. Authenticating against the API

Authenticating against the API

import axios from 'axios';

const getToken = async () => {
  const response = await axios({
    method: 'post',
    url: 'https://api.felloh.com/token',
    headers: {
      'Content-Type': 'application/json'
    },
    data: JSON.stringify({
        public_key: process.env.PUBLIC_KEY,
        private_key: process.env.PRIVATE_KEY,
      },
    ),
  });


  return response.data.data;
};

const { token } = await getToken();

use GuzzleHttp\Client;

function getToken() {
  $client = new Client();
  $response = $client->post('https://api.felloh.com/token', [
    'headers' => [
      'Content-Type' => 'application/json',
    ],
    'json' => [
      'public_key' => getenv('PUBLIC_KEY'),
      'private_key' => getenv('PRIVATE_KEY'),
    ],
  ]);

  $data = json_decode($response->getBody(), true);
  return $data['data'];
}

$token = getToken()['token'];

import requests
import os

def get_token():
    url = 'https://api.felloh.com/token'
    public_key = os.environ.get('PUBLIC_KEY')
    private_key = os.environ.get('PRIVATE_KEY')

    payload = {
        'public_key': public_key,
        'private_key': private_key
    }

    headers = {
        'Content-Type': 'application/json'
    }

    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()

    token = response.json()['data']
    
    return token

token = get_token()
print(token)

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var token = await GetToken();
        Console.WriteLine(token);
    }

    static async Task<string> GetToken()
    {
        using (var httpClient = new HttpClient())
        {
            var url = "https://api.felloh.com/token";
            var publicKey = Environment.GetEnvironmentVariable("PUBLIC_KEY");
            var privateKey = Environment.GetEnvironmentVariable("PRIVATE_KEY");

            var requestData = new
            {
                public_key = publicKey,
                private_key = privateKey
            };

            var jsonContent = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(requestData), Encoding.UTF8, "application/json");

            var response = await httpClient.PostAsync(url, jsonContent);
            response.EnsureSuccessStatusCode();

            var responseData = await response.Content.ReadAsStringAsync();
            var token = Newtonsoft.Json.JsonConvert.DeserializeObject<dynamic>(responseData).data;

            return token;
        }
    }
}

you will need to authenticate against our api and get the bearer token, you can then use this for all future calls against the API.

You will need to get your public and private keys from the dashboard and them set these either in the environment or via another method.

More information on authentication can be found here.

2. Creating a pre-authorised payment link

Creating a payment link

import axios from 'axios';

const response = await axios(
  {
    method: 'put',
    url: `https://api.felloh.com/agent/payment-links`,
    data : JSON.stringify({
        customer_name: 'Tom Brady',
        email: 'tom@felloh.com',
        booking_id: '226009ab-ffe9-4c80-922b-982e8e7849f8',
        customer_id: 'cc15e9a7-21bf-4d55-b500-2a24c8e4ed1e',
        amount: 20000, 
        currency: 'GBX',
        organisation: 'X1234',
        open_banking_enabled: true,
        card_enabled: true,
        description: 'Final payment for cruise holiday',
        expires_at: '2022-07-25',
        type: "UNKNOWN",
        authorisation_only: true,
      },
    }),
    headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer <YOUR TOKEN HERE>`,
    },
  },
);

use GuzzleHttp\Client;

function createPaymentLink($token, $data) {
  $url = "https://api.felloh.com/agent/payment-links";

  $client = new Client();
  $response = $client->put($url, [
    'json' => $data,
    'headers' => [
      'Content-Type' => 'application/json',
      'Authorization' => "Bearer $token",
    ],
  ]);

  return $response->getBody();
}

$token = "<YOUR TOKEN HERE>";
$data = [
  'customer_name' => 'Tom Brady',
  'email' => 'tom@felloh.com',
  'booking_id' => '226009ab-ffe9-4c80-922b-982e8e7849f8',
  'customer_id' => 'cc15e9a7-21bf-4d55-b500-2a24c8e4ed1e',
  'amount' => 20000,
  'currency' => 'GBX',
  'organisation' => 'X1234',
  'open_banking_enabled' => true,
  'card_enabled' => true,
  'description' => 'Final payment for cruise holiday',
  'expires_at' => '2022-07-25',
  'authorisation_only' => true,
];

$response = createPaymentLink($token, $data);

import requests
import json

def create_payment_link(token):
    url = 'https://api.felloh.com/agent/payment-links'

    payload = {
        'customer_name': 'Tom Brady',
        'email': 'tom@felloh.com',
        'booking_id': '226009ab-ffe9-4c80-922b-982e8e7849f8',
        'customer_id': 'cc15e9a7-21bf-4d55-b500-2a24c8e4ed1e',
        'amount': 20000,
        'currency': 'GBX',
        'organisation': 'X1234',
        'open_banking_enabled': True,
        'card_enabled': True,
        'description': 'Final payment for cruise holiday',
        'expires_at': '2022-07-25',
        'type': 'UNKNOWN',
        'authorisation_only': True
    }

    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.put(url, data=json.dumps(payload), headers=headers)
    response.raise_for_status()

    payment_link = response.json()['data']
    
    return payment_link

payment_link = create_payment_link('<YOUR TOKEN HERE>')
print(payment_link)

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var token = "<YOUR TOKEN HERE>";
        var paymentLinkResponse = await CreatePaymentLink(token);
        Console.WriteLine(paymentLinkResponse);
    }

    static async Task<string> CreatePaymentLink(string token)
    {
        using (var httpClient = new HttpClient())
        {
            var url = "https://api.felloh.com/agent/payment-links";

            var requestData = new
            {
                customer_name = "Tom Brady",
                email = "tom@felloh.com",
                booking_id = "226009ab-ffe9-4c80-922b-982e8e7849f8",
                customer_id = "cc15e9a7-21bf-4d55-b500-2a24c8e4ed1e",
                amount = 20000,
                currency = "GBX",
                organisation = "X1234",
                open_banking_enabled = true,
                card_enabled = true,
                description = "Final payment for cruise holiday",
                expires_at = "2022-07-25",
                type = "UNKNOWN",
                authorisation_only = true
            };

            var jsonContent = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(requestData), Encoding.UTF8, "application/json");

            httpClient.DefaultRequestHeaders.Add("Content-Type", "application/json");
            httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");

            var response = await httpClient.PutAsync(url, jsonContent);
            response.EnsureSuccessStatusCode();

            var responseData = await response.Content.ReadAsStringAsync();
            var paymentLink = Newtonsoft.Json.JsonConvert.DeserializeObject<dynamic>(responseData).data;

            return paymentLink;
        }
    }
}

By setting authorisation_only to true in the request, you are telling the API that you want to pre-authorise the payment. The same can be done for ecommerce (embedded) payments.

API documentation on creating payment links can be found here or alternatively ecommerce (embedded) payments can be found here.

3. Complete (capture) the transaction

Complete a transaction

import axios from 'axios';

const transactionID = '226009ab-ffe9-4c80-922b-982e8e7849f8';

const response = await axios(
  {
    method: 'get',
    url: `https://api.felloh.com/agent/transactions${transactionID}/complete`,
    headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer <YOUR TOKEN HERE>`,
    },
  },
);

use GuzzleHttp\Client;

function completeTransaction($token, $amount) {
  $url = "https://api.felloh.com/agent/transactions/226009ab-ffe9-4c80-922b-982e8e7849f8/complete";

  $client = new Client();
  $response = $client->get($url, [
    'headers' => [
      'Content-Type' => 'application/json',
      'Authorization' => "Bearer $token",
    ],
  ]);

  $data = json_decode($response->getBody(), true);
  return $data;
}

$token = "<YOUR TOKEN HERE>";
$response = completeTransaction($token);

import requests

def complete_transaction(token, transaction_id):
    url = f'https://api.felloh.com/agent/transactions/{transaction_id}/complete'

    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.get(url, headers=headers)
    response.raise_for_status()

    result = response.json()['data']
    
    return result

transaction_id = '226009ab-ffe9-4c80-922b-982e8e7849f8'
result = complete_transaction('<YOUR TOKEN HERE>', transaction_id)
print(result)

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var token = "<YOUR TOKEN HERE>";
        var transactionId = "226009ab-ffe9-4c80-922b-982e8e7849f8";
        var response = await CompleteTransaction(token, transactionId);
        Console.WriteLine(response);
    }

    static async Task<string> CompleteTransaction(string token, string transactionId)
    {
        using (var httpClient = new HttpClient())
        {
            var url = $"https://api.felloh.com/agent/transactions/{transactionId}/complete";

            httpClient.DefaultRequestHeaders.Add("Content-Type", "application/json");
            httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");

            var response = await httpClient.GetAsync(url);
            response.EnsureSuccessStatusCode();

            var responseData = await response.Content.ReadAsStringAsync();
            var result = Newtonsoft.Json.JsonConvert.DeserializeObject<dynamic>(responseData).data;

            return result;
        }
    }
}

To complete a transaction, you will need to make a GET request to the API, passing in the transaction ID. This will then complete the transaction and the funds will be taken from the customer.

API documentation on completing a transaction can be found here and reversing a transaction can be found here.