Refund a Payment

This feature must be enabled by your account manager and is not available by default.

We approach refunds as a multistep process, users (including api users) with the refund:request role can request a refund, this will create a refund request in the system. Users with the refund:approve role can then approve the refund request, this will create a refund in the system. The refund will then be processed by the system and the funds will be returned to the customer.

1. Authenticating against the API

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.


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();

More information on authentication can be found here.

2. Generating a Refund Request

The 'refund:request' role is required on your api keys to call this endpoint.

This will generate a refund request in the system, this will be visible in the dashboard or via the refund endpoint, which can then be approved by a user or via the API.


import axios from 'axios';

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

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

API documentation for this endpoint can be found here.

3. Listing All Refunds

The 'refund:list' role is required on your api keys to call this endpoint.

Calling this endpoint will allow you to list all refunds in the system. This will allow you to get the authorisation_code for the refund you want to approve.

This can also be found be calling the transaction endpoint, which will now have a refund object attached to it, with its authorisation code.


import axios from 'axios';

const response = await axios(
  {
    method: 'post',
    url: 'https://api.felloh.com/agent/refunds',
    data: {
        organisation: 'X9876',
        skip: 10,
        take: 20
    },
    headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer <YOUR TOKEN HERE>`,
    },
  },
);

4. Authorise the refund

The 'refund:approve' role is required on your api keys to call this endpoint.

Once the refund has been approved, you can then call the authorise endpoint, this will then send the refund to the acquirer for processing.


import axios from 'axios';

const authroisationCode = '8004d669-2875-45b6-a2ce-d08ae79029ae';

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

More information can be found regarding the approval and decline methods can be found here.