Core concepts

Payments

Customers pay approved invoices online with Paystack. You start the payment; Flux verifies it with Paystack and tells you by webhook.

1. You

   Start the payment

   POST /invoices/{id}/checkout returns a Paystack URL. Or give the payer the signed payUrl.

2. Payer

   Pays on Paystack

   By card, transfer or any channel Paystack offers. Paystack redirects them back.

3. Flux

   Verifies

   Flux checks the payment with Paystack: the money must cover the invoice total, in its currency.

4. Flux → you

   Tells you

   payment.succeeded, invoice.paid and receipt.issued. Or payment.failed.

Online and offline invoices#

When an invoice is approved, the organization decides how it's paid: online (Paystack) or offline (bank transfer). Only online invoices can be paid through the API or a payUrl. Starting a checkout for an offline invoice gets 409 not_online.

Starting a payment#

There are two ways. Both reach the same Paystack checkout.

• Checkout: call POST /invoices/{id}/checkout (scope payments:write) and redirect the payer to checkoutUrl.
• Pay link: give the payer the signed payUrl from POST /invoices/{id}/links. Opening it starts the checkout. No payment scope is needed. See Signed links.

curl -X POST "$FLUX_BASE_URL/api/v1/invoices/5012/checkout" \
  -H "Authorization: ApiKey $FLUX_API_KEY"

// Node.js 18+ (built-in fetch). Save as an .mjs file.
const response = await fetch(`${process.env.FLUX_BASE_URL}/api/v1/invoices/5012/checkout`, {
  method: "POST",
  headers: {
    Authorization: `ApiKey ${process.env.FLUX_API_KEY}`,
  },
});
console.log(response.status, await response.json());

import os

import requests

response = requests.post(
    f"{os.environ['FLUX_BASE_URL']}/api/v1/invoices/5012/checkout",
    headers={"Authorization": f"ApiKey {os.environ['FLUX_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

<?php
$ch = curl_init(getenv('FLUX_BASE_URL') . '/api/v1/invoices/5012/checkout');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: ApiKey ' . getenv('FLUX_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;

using System.Net.Http.Headers;

var baseUrl = Environment.GetEnvironmentVariable("FLUX_BASE_URL");
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("ApiKey", Environment.GetEnvironmentVariable("FLUX_API_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Post, $"{baseUrl}/api/v1/invoices/5012/checkout");

using var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("POST", os.Getenv("FLUX_BASE_URL")+"/api/v1/invoices/5012/checkout", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "ApiKey "+os.Getenv("FLUX_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

{
  "checkoutUrl": "https://checkout.paystack.com/7xk2m9q4fz0b1ac"
}

Confirmation is asynchronous#

• Flux verifies every payment with Paystack itself.
• An invoice is marked paid only when the amount paid covers the invoice total in the invoice's currency. Paying more, for example when the payer covers gateway fees, is accepted.
• A short payment, or one in another currency, isn't applied. The invoice stays unpaid, and Flux sends payment.failed (with problem saying why) and invoice.payment_review. The organization sorts it out in Flux.
• Listen for payment.succeeded, invoice.paid or receipt.issued. If you can't receive webhooks, poll GET /invoices/{id} until status is paid.

Events can arrive in a different order than they were emitted. Re-read the invoice when order matters.

Fees#

• The payer bears Paystack's fee.
• When the organization collects through Flux's Paystack account: Flux adds a platform fee to the amount the payer pays: a flat amount plus a percentage, capped. It's shown as platformFeeMinor on payment.initiated. whether to publish the fee figures
• Organizations on their own Paystack account pay no platform fee.

Refunds#

Refunds are made in Paystack. Flux records them and sends payment.refunded, with the amount in minor units. Whether to reverse the invoice is an accounting decision taken in Flux, not by the API.