Managing payouts

Once a payout has been created, it can be modified, deleted or submitted for payment. This page provides examples of:

selecting pending payouts.
updating a pending payout.
deleting a payout.

To see how to submit a payout, see the examples for authorizing a payout for payment.

Selecting pending payouts

A payout can be selected by for approval by using the payouts/{id} GET action as shown below. Note that response data also includes the approval URL:

using System.Net.Http.Json;

const string baseUrl = "<<SANDBOX_URL>>payouts";

var jwtToken = Environment.GetEnvironmentVariable("NOFRIXION_USER_TOKEN");

// specify id of payout to return
string payoutId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Accept", "application/json");
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {jwtToken}");

try
{
    var response = await client.GetAsync($"{baseUrl}/{payoutId}");
    if (response.IsSuccessStatusCode)
    {
        // returns requested payout
        var payout = await response.Content.ReadFromJsonAsync<Payout>();
        if (payout != null)
        {
            // displays payout data
            Console.WriteLine(payout);
        }
    }
    else
    {
        // HTTP error codes will return a MoneyMoov API problem object
        Console.WriteLine(await response.Content.ReadFromJsonAsync<ApiProblem>());
    }
}
catch (Exception e)
{
    Console.WriteLine($"Error: {e.Message}");
}

// Type declarations for returned data
record Payout(string currentUserID, string currentUserRole, string approvePayoutUrl, string id,
                string accountID, string userID, string type, string description, string currency,
                decimal amount, string yourReference, string destinationIBAN, string destinationAccountID,
                string destinationAccountName, string theirReference);

record ApiProblem(string type, string title, int status, string detail);

// This module allows the code to run on Node.js, it's not required if running in a browser.
const fetch = require('cross-fetch');

// Remember, the JWT access token must be securely store - this example uses an environment variable
const jwtToken = process.env.NOFRIXION_USER_TOKEN;

const baseUrl = '<<SANDBOX_URL>>payouts/';

// You need to specify payout Id. 
// The payout ID of a newly created payout is returned by the /payouts endpoint POST method,
// a list of pending payouts can also be retreived using the /payouts endpoint GET method.
var payoutId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

const options = {
    method: 'GET',
    headers: {
        Accept: 'application/json',
        Authorization: 'Bearer ' + jwtToken
    }
};

fetch(baseUrl + payoutId, options)
    .then(response => response.json())
    // Get the approval URL
    .then(responseJson => {
        // responseJson contains all payout details
        console.log(responseJson);
        // can also get the approval URL for a payout using this method.
        console.log(responseJson.approvePayoutUrl);
    })
    .catch(err => console.error(err));

# The 'requests' module for Python can be used to make calls to the MoneyMoov API in popular python frameworks such as Django and Flask.
import requests
import os

# Remember, the JWT access token must be securely stored ('os' module above allows storage in environment variable)
jwtToken = os.environ['NOFRIXION_USER_TOKEN']

baseUrl = "<<SANDBOX_URL>>payouts"

# id of required payout must be specified
payoutId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {jwtToken}"
}

response = requests.request("GET", f"{baseUrl}/{payoutId}", headers=headers)

if response.ok:
    payout = response.json()

    # print payout object
    print(payout)
    print() 

    # Use the 'approvePayoutUrl' key for approving payouts.
    print(payout['approvePayoutUrl'])
else:
    # If not OK, response contains MoneyMoov problem (https://docs.nofrixion.com/reference/error-messages)
    print(response.json())

If you are batch processing payouts, or have an approval process, you may prefer to retrieve a list of all pending payouts for the current merchant. The /payouts GET action returns a page of pending payouts:

using System.Net.Http.Json;

const string baseUrl = "<<SANDBOX_URL>>payouts";

var jwtToken = Environment.GetEnvironmentVariable("NOFRIXION_USER_TOKEN");

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Accept", "application/json");
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {jwtToken}");

// Note optionalurl paramaters for paging the payout list are exposed in the API
// - see https://api-sandbox.nofrixion.com/swagger/index.html for full details

try
{
    var response = await client.GetAsync(baseUrl);
    if (response.IsSuccessStatusCode)
    {
        // returns a list of payouts
        var payoutsPage = await response.Content.ReadFromJsonAsync<PayoutsPage>();
        if (payoutsPage != null)
        {
            // Do something with response...
            Console.WriteLine($"Showing page {payoutsPage.pageNumber} of {payoutsPage.totalPages}.");
            foreach (var payout in payoutsPage.content)
            {
                Console.WriteLine($"Send {payout.currency} {payout.amount:0.00} to {payout.destinationIban} ({payout.yourReference})");
            }
        }
        else
        {
            Console.WriteLine("No payouts returned.");
        }
    }
    else
    {
        // HTTP error codes will return a MoneyMoov API problem object
        Console.WriteLine(await response.Content.ReadFromJsonAsync<ApiProblem>());
    }
}
catch (Exception e)
{
    Console.WriteLine($"Error: {e.Message}");
}

// type definitions for returned data
record Payout(string id, string accountID, string userID, string type, string description,
            string currency, decimal amount, string yourReference, string destinationIban,
            string destinationAccountName, string theirReference);
record PayoutsPage(List<Payout> content, int pageNumber, int pageSize, int totalPages, int totalSize);
record ApiProblem(string type, string title, int status, string detail);

// This module allows the code to run on Node.js, it's not required if running in a browser.
const fetch = require('cross-fetch');

// Remember, the JWT access token must be securely store - this example uses an environment variable
const jwtToken = process.env.NOFRIXION_USER_TOKEN;

const url = '<<SANDBOX_URL>>payouts';

// Note optional url paramaters for paging the payout list are exposed in the API
// - see https://api-sandbox.nofrixion.com/swagger/index.html for full details

const options = {
    method: 'GET',
    headers: {
        Accept: 'application/json',
        Authorization: 'Bearer ' + jwtToken
    }
};

fetch(url, options)
    .then(response => response.json())
    .then(responseJson => console.log(responseJson))
    .catch(err => console.error(err));

# The 'requests' module for Python can be used to make calls to the MoneyMoov API in popular python frameworks such as Django and Flask.
import requests
import os

# Remember, the JWT access token must be securely stored ('os' module above allows storage in environment variable)
jwtToken = os.environ['NOFRIXION_USER_TOKEN']

baseUrl = "<<SANDBOX_URL>>payouts"

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {jwtToken}"
}

response = requests.request("GET", baseUrl, headers=headers)

if response.ok:
    # The response data is a JSON object containing:
    # - content: a property that is an array of payout objects
    # - metdata fields: 'pageNumber', 'pageSize', 'totalPages', 'totalSize'
    #   - these can be used to help with pagination of results (and can be passed in the query string)
    data = response.json()

    # For exmaple: view keys/values for each payout in the content property
    for payout in data["content"]:
        for payoutField in payout.keys():
            print(f"{payoutField}: {payout[payoutField]}")
        # Print a blank line between payouts for readability
        print()

    # Display metadata
    print(f"Retrieved page {data['pageNumber']} of {data['totalPages']} payout pages.")
else:
    # If not OK, response contains MoneyMoov problem (https://docs.nofrixion.com/reference/error-messages)
    print(response.json())

Updating a payout

If a payout needs to be updated prior to submission, this can be done by calling the "PUT" method against the /payouts/{id} endpoint as shown below:

using System.Net.Http.Json;

const string baseUrl = "<<SANDBOX_URL>>payouts";

var jwtToken = Environment.GetEnvironmentVariable("NOFRIXION_USER_TOKEN");

// specify id of payout to update
string payoutId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Accept", "application/json");
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {jwtToken}");

var data = new Dictionary<string, string>();
data.Add("AccountID", "A120P0JR");
data.Add("Currency", "EUR");
data.Add("Amount", "1.99");
data.Add("YourReference", "Updated Payment");
data.Add("DestinationIBAN", "GB94BARC10201530093459");
data.Add("DestinationAccountName", "Dest Name");
data.Add("TheirReference", "Their Ref");

HttpContent postData = new FormUrlEncodedContent(data);

try
{
    var response = await client.PutAsync($"{baseUrl}/{payoutId}", postData);
    if (response.IsSuccessStatusCode)
    {
        // "OK" on success
        Console.WriteLine(response.StatusCode);

        // The newly created payout object will be returned in the response body
        Console.WriteLine(await response.Content.ReadFromJsonAsync<Payout>());
    }
    else
    {
        // HTTP error codes will return a MoneyMoov API problem object
        Console.WriteLine(await response.Content.ReadFromJsonAsync<ApiProblem>());
    }
}
catch (Exception e)
{
    Console.WriteLine($"Error: {e.Message}");
}

// Type definitions for returned data
record Payout(string currentUserID, string currentUserRole, string approvePayoutUrl, string id,
                string accountID, string userID, string type, string description, string currency,
                decimal amount, string yourReference, string destinationAccountID, string destinationIBAN,
                string destinationAccountName, string theirReference);

record ApiProblem(string type, string title, int status, string detail);

// These packages allow the code to run on Node.js, they aren't required if running in a browser.
const fetch = require('cross-fetch');
const FormData = require('form-data');

// Remember, the JWT access token must be securely store - this example uses an environment variable
const jwtToken = process.env.NOFRIXION_USER_TOKEN;

const url = '<<SANDBOX_URL>>/payouts/';

// need to specify payout Id to update
var payoutId = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

// Build payoutData object with updated details, could also get from form in front-end applications.
let payoutData = new FormData();
payoutData.append('AccountID', 'A120P0JR');
payoutData.append('Currency', 'EUR');
payoutData.append('Amount', '1.99');
payoutData.append('YourReference', 'Updated payout');
payoutData.append('DestinationIBAN', 'GB33BUKB20201555555555');
payoutData.append('DestinationAccountName', 'Destination Name');
payoutData.append('TheirReference', 'Their reference');

const options = {
    method: 'PUT',
    headers: {
        Accept: 'application/json',
        Authorization: 'Bearer ' + jwtToken
    },
    body: payoutData
};

fetch(url + payoutId, options)
    .then(response => response.json())
    // Response object containsd details of the updated payout.
    .then(responseJson => console.log(responseJson))
    .catch(err => console.error(err));

# The 'requests' library for Python can be used to make calls to the MoneyMoov API in popular python frameworks such as Django and Flask.
import requests
import os

# Remember, the JWT access token must be securely stored ('os' module above allows storage in environment variable)
jwtToken = os.environ['NOFRIXION_USER_TOKEN']

baseUrl = "<<SANDBOX_URL>>payouts"

# id of payout to update must be specified
payoutId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {jwtToken}"
}

payoutData = {
    "AccountID": "A120P0JR",
    "Currency": "EUR",
    "Amount": "0.01",
    "YourReference": "Updated payout",
    "DestinationIBAN": "GB94BARC10201530093459",
    "DestinationAccountName": "Destination Name",
    "TheirReference": "Their reference"
}

response = requests.request("PUT", f"{baseUrl}/{payoutId}", headers=headers, data=payoutData)

if response.ok:
    # API returns updated payout object response body.
    print(response.json())
else:
    # If not OK, response contains MoneyMoov problem ( see https://docs.nofrixion.com/reference/error-messages for details)
    print(response.json())

Deleting a payout

Payouts can be deleted using the "DELETE" method against the "/payouts/{id}" endpoint and specifying the relevant payout id. For example:

using System.Net.Http.Json;

//Remember to keep the JWT token safe and secure.
var jwtToken = Environment.GetEnvironmentVariable("NOFRIXION_USER_TOKEN");

string baseUrl = "<<SANDBOX_URL>>payouts";

var client = new HttpClient();

client.DefaultRequestHeaders.Add("Accept", "application/json");
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {jwtToken}");


// need to specify payout Id
string payoutId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

HttpResponseMessage response = await client.DeleteAsync($"{baseUrl}/{payoutId}");
if (response.IsSuccessStatusCode)
{
    // HTTP status code OK on success
    Console.WriteLine(response.StatusCode);
}
else
{
    // HTTP error codes will return a MoneyMoov API problem object
    Console.WriteLine(await response.Content.ReadFromJsonAsync<ApiProblem>());
}

record ApiProblem(string type, string title, int status, string detail);

// This module allows the code to run on Node.js, it's not required if running in a browser.
const fetch = require("cross-fetch");

// Remember, the JWT access token must be securely store - this example uses an environment variable
const jwtToken = process.env.NOFRIXION_USER_TOKEN;

const url = "<<SANDBOX_URL>>payouts/";

// need to specify payout Id
var payoutId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

const options = {
    method: "DELETE",
    headers: {
        Accept: "application/json",
        Authorization: "Bearer " + jwtToken
    }
};

fetch(url + payoutId, options)
    .then(response => response.status)
    // Should get response status 200 on success
    .then(respStatus => console.log(respStatus))
    .catch(err => console.error(err));

# The 'requests' library for Python can be used to make calls to the MoneyMoov API in popular python frameworks such as Django and Flask.
import requests
import os

# Remember, the JWT access token must be securely stored ('os' module above allows storage in environment variable)
jwtToken = os.environ['NOFRIXION_USER_TOKEN']

baseUrl = "<<SANDBOX_URL>>payouts"

# id of payout to delete must be specified
payoutId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {jwtToken}"
}

response = requests.request("DELETE", f"{baseUrl}/{payoutId}", headers=headers)

if response.ok:
    # Process response / reason. Expect "200: OK" on success
    print(f"{response.status_code}: {response.reason}")
else:
    # If not OK, response contains MoneyMoov problem (https://docs.nofrixion.com/reference/error-messages)
    print(response.json())