Documentation

Payment request status

Remember, when working with payment requests use a MERCHANT access token.

With some payments, particularly those involving cards, processing does not occur instantly. The paymentrequests/{id}/result and paymentrequests/{id}/events GET actions allow you to view the status of and events relating to a payment request.

Payment request results

The paymentrequests/{id}/result GET action provides a summary of the status of a payment request. The JSON object returned by the method contains a result property, which can be set to any of the following values:

  • FullyPaid: The payment attempt was successful and the request amount has been fully paid.
  • PartiallyPaid: The payment attempt was successful but the amount paid was less than the requested amount.
  • OverPaid: Payments over the expected amount have been received.
  • Voided: For card payments, the payment was voided prior to settlement.
  • None: No events have been recorded for the payment request.

The following examples show how to call the method:

using System.Net.Http.Json;
using System.Text.Json;

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

// Payment requests use MERCHANT tokens (remember to keep these safe and secure).
var jwtToken = Environment.GetEnvironmentVariable("NOFRIXION_MERCHANT_TOKEN");

var client = new HttpClient();

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

string paymentRequestID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

try
{
    HttpResponseMessage response = await client.GetAsync($"{baseUrl}/{paymentRequestID}/result");
    if (response.IsSuccessStatusCode)
    {
        // JSON object containing payment request results
        var result = await response.Content.ReadFromJsonAsync<PaymentRequestResult>();
        if (result != null)
        {
            // do something with the result object
            var resultString = JsonSerializer.Serialize<PaymentRequestResult>(result);
            Console.WriteLine(resultString);
        }
    }
    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 definition for response data
record PaymentRequestPayment(string paymentRequestID, string occuredAt, string paymentMethod, decimal amount,
                string currency, string cardTokenCustomerID, string cardTransactionID, string cardAuthorizationID,
                decimal cardCaptureAmount, bool cardIsVoided);

record PaymentRequestResult(string paymentRequestID, decimal amount, string currency,
                string result, List<PaymentRequestPayment> payments);

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

// These modules allow the code to run on Node.js, they aren't 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_MERCHANT_TOKEN;

const baseUrl = '<<SANDBOX_URL>>paymentrequests';

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

var paymentRequestID = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

fetch(`${baseUrl}/${paymentRequestID}/result`, options)
    .then(response => response.json())
    // the response JSON contains the payment response object.
    .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)
# ... and when dealing with payment requests, use a MERCHANT token!
jwtToken = os.environ['NOFRIXION_MERCHANT_TOKEN']

baseUrl = "<<SANDBOX_URL>>paymentrequests"
paymentRequestID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

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

try:
    response = requests.request("GET", f"{baseUrl}/{paymentRequestID}/result", headers=headers)

    if response.ok:
        #  If successful, the API returns the payment request result object
        print(response.json())
    else:
        # If not OK, response contains MoneyMoov problem (https://docs.nofrixion.com/reference/error-messages)
        print(response.json())

except Exception as ex:
    print(ex)

Payment request events

There are a series of events associated with the fulfilment of a payment request. The paymentrequests/{id}/events GET action provides a detailed list of these events as shown in the following examples:

using System.Net.Http.Json;
using System.Text.Json;

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

// Payment requests use MERCHANT tokens (remember to keep these safe and secure).
var jwtToken = Environment.GetEnvironmentVariable("NOFRIXION_MERCHANT_TOKEN");

var client = new HttpClient();

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

string paymentRequestID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

try
{
    HttpResponseMessage response = await client.GetAsync($"{baseUrl}/{paymentRequestID}/events");
    if (response.IsSuccessStatusCode)
    {
        // returns JSON objects aray of payment request events, do something with this....
        var events = await response.Content.ReadFromJsonAsync<List<PaymentRequestEvent>>();
        if (events != null)
        {
            foreach (PaymentRequestEvent ev in events) {
            var eventString = JsonSerializer.Serialize<PaymentRequestEvent>(ev);
            Console.WriteLine(eventString);

            }
        }
    }
    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 definition for response data
record PaymentRequestEvent(string id, string paymentRequestID, string inserted, string eventType, decimal amount, 
                string currency, string status, string errorReason, string errorMessage, string cardRequestId, 
                string cardTransactionID, string cardTokenCustomerID, string cardAuthorizationResponseID,
                string lightningInvoice, string pispPaymentServiceProviderID, string pispPaymentInitiationID,
                string pispRedirectUrl);

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

// These modules allow the code to run on Node.js, they aren't 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_MERCHANT_TOKEN;

const baseUrl = '<<SANDBOX_URL>paymentrequests';

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

var paymentRequestID = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

fetch(`${baseUrl}/${paymentRequestID}/events`, options)
    .then(response => response.json())
    // the returned JSON contains the payment request response object.
    .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)
# ... and when dealing with payment requests, use a MERCHANT token!
jwtToken = os.environ['NOFRIXION_MERCHANT_TOKEN']

baseUrl = "<<SANDBOX_URL>>paymentrequests"
paymentRequestID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

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

try:
    response = requests.request("GET", f"{baseUrl}/{paymentRequestID}/events", headers=headers)

    if response.ok:
        #  If successful, the API returns an array payment request event objects
        print(response.json())
    else:
        # If not OK, response contains MoneyMoov problem (https://docs.nofrixion.com/reference/error-messages)
        print(response.json())

except Exception as ex:
    print(ex)