curl --request POST \
--url https://api.spotflow.co/api/v1/payments/initialize \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reference": "string",
"currency": "USD",
"customer": {
"email": "john@example.com"
},
"amount": 5,
"expiresIn": 10,
"planId": "95eb086a-b11a-44b2-8422-a1955ca0fd9a",
"applyDiscount": "true OR false",
"countryCode": "CI",
"localCurrency": "NGN",
"callBackUrl": "https://yourapp.com/callback",
"metadata": {
"productName": "Algo.ai"
}
}
'import requests
url = "https://api.spotflow.co/api/v1/payments/initialize"
payload = {
"reference": "string",
"currency": "USD",
"customer": { "email": "john@example.com" },
"amount": 5,
"expiresIn": 10,
"planId": "95eb086a-b11a-44b2-8422-a1955ca0fd9a",
"applyDiscount": "true OR false",
"countryCode": "CI",
"localCurrency": "NGN",
"callBackUrl": "https://yourapp.com/callback",
"metadata": { "productName": "Algo.ai" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
reference: 'string',
currency: 'USD',
customer: {email: 'john@example.com'},
amount: 5,
expiresIn: 10,
planId: '95eb086a-b11a-44b2-8422-a1955ca0fd9a',
applyDiscount: 'true OR false',
countryCode: 'CI',
localCurrency: 'NGN',
callBackUrl: 'https://yourapp.com/callback',
metadata: {productName: 'Algo.ai'}
})
};
fetch('https://api.spotflow.co/api/v1/payments/initialize', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.spotflow.co/api/v1/payments/initialize",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reference' => 'string',
'currency' => 'USD',
'customer' => [
'email' => 'john@example.com'
],
'amount' => 5,
'expiresIn' => 10,
'planId' => '95eb086a-b11a-44b2-8422-a1955ca0fd9a',
'applyDiscount' => 'true OR false',
'countryCode' => 'CI',
'localCurrency' => 'NGN',
'callBackUrl' => 'https://yourapp.com/callback',
'metadata' => [
'productName' => 'Algo.ai'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.spotflow.co/api/v1/payments/initialize"
payload := strings.NewReader("{\n \"reference\": \"string\",\n \"currency\": \"USD\",\n \"customer\": {\n \"email\": \"john@example.com\"\n },\n \"amount\": 5,\n \"expiresIn\": 10,\n \"planId\": \"95eb086a-b11a-44b2-8422-a1955ca0fd9a\",\n \"applyDiscount\": \"true OR false\",\n \"countryCode\": \"CI\",\n \"localCurrency\": \"NGN\",\n \"callBackUrl\": \"https://yourapp.com/callback\",\n \"metadata\": {\n \"productName\": \"Algo.ai\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.spotflow.co/api/v1/payments/initialize")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reference\": \"string\",\n \"currency\": \"USD\",\n \"customer\": {\n \"email\": \"john@example.com\"\n },\n \"amount\": 5,\n \"expiresIn\": 10,\n \"planId\": \"95eb086a-b11a-44b2-8422-a1955ca0fd9a\",\n \"applyDiscount\": \"true OR false\",\n \"countryCode\": \"CI\",\n \"localCurrency\": \"NGN\",\n \"callBackUrl\": \"https://yourapp.com/callback\",\n \"metadata\": {\n \"productName\": \"Algo.ai\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.spotflow.co/api/v1/payments/initialize")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reference\": \"string\",\n \"currency\": \"USD\",\n \"customer\": {\n \"email\": \"john@example.com\"\n },\n \"amount\": 5,\n \"expiresIn\": 10,\n \"planId\": \"95eb086a-b11a-44b2-8422-a1955ca0fd9a\",\n \"applyDiscount\": \"true OR false\",\n \"countryCode\": \"CI\",\n \"localCurrency\": \"NGN\",\n \"callBackUrl\": \"https://yourapp.com/callback\",\n \"metadata\": {\n \"productName\": \"Algo.ai\"\n }\n}"
response = http.request(request)
puts response.read_body{
"reference": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"checkoutUrl": "https://checkout.spotflow.co/paymentCode",
"paymentCode": "PAY123456789",
"status": "pending",
"mode": "TEST",
"expiryTime": "2025-11-03T10:16:26.948278058",
"callBackUrl": "https://yourapp.com/callback",
"metadata": {
"productName": "Algo.ai"
}
}{
"error": "Missing Parameter",
"message": "missing_parameter",
"status": 400
}{
"error": "Unauthorized",
"message": "invalid_credentials",
"status": 401
}Initialize Payment
This is Spotflow’s Redirect Checkout. Initiate a payment request to generate a unique payment reference, payment code and checkout URL for your customers
curl --request POST \
--url https://api.spotflow.co/api/v1/payments/initialize \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reference": "string",
"currency": "USD",
"customer": {
"email": "john@example.com"
},
"amount": 5,
"expiresIn": 10,
"planId": "95eb086a-b11a-44b2-8422-a1955ca0fd9a",
"applyDiscount": "true OR false",
"countryCode": "CI",
"localCurrency": "NGN",
"callBackUrl": "https://yourapp.com/callback",
"metadata": {
"productName": "Algo.ai"
}
}
'import requests
url = "https://api.spotflow.co/api/v1/payments/initialize"
payload = {
"reference": "string",
"currency": "USD",
"customer": { "email": "john@example.com" },
"amount": 5,
"expiresIn": 10,
"planId": "95eb086a-b11a-44b2-8422-a1955ca0fd9a",
"applyDiscount": "true OR false",
"countryCode": "CI",
"localCurrency": "NGN",
"callBackUrl": "https://yourapp.com/callback",
"metadata": { "productName": "Algo.ai" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
reference: 'string',
currency: 'USD',
customer: {email: 'john@example.com'},
amount: 5,
expiresIn: 10,
planId: '95eb086a-b11a-44b2-8422-a1955ca0fd9a',
applyDiscount: 'true OR false',
countryCode: 'CI',
localCurrency: 'NGN',
callBackUrl: 'https://yourapp.com/callback',
metadata: {productName: 'Algo.ai'}
})
};
fetch('https://api.spotflow.co/api/v1/payments/initialize', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.spotflow.co/api/v1/payments/initialize",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reference' => 'string',
'currency' => 'USD',
'customer' => [
'email' => 'john@example.com'
],
'amount' => 5,
'expiresIn' => 10,
'planId' => '95eb086a-b11a-44b2-8422-a1955ca0fd9a',
'applyDiscount' => 'true OR false',
'countryCode' => 'CI',
'localCurrency' => 'NGN',
'callBackUrl' => 'https://yourapp.com/callback',
'metadata' => [
'productName' => 'Algo.ai'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.spotflow.co/api/v1/payments/initialize"
payload := strings.NewReader("{\n \"reference\": \"string\",\n \"currency\": \"USD\",\n \"customer\": {\n \"email\": \"john@example.com\"\n },\n \"amount\": 5,\n \"expiresIn\": 10,\n \"planId\": \"95eb086a-b11a-44b2-8422-a1955ca0fd9a\",\n \"applyDiscount\": \"true OR false\",\n \"countryCode\": \"CI\",\n \"localCurrency\": \"NGN\",\n \"callBackUrl\": \"https://yourapp.com/callback\",\n \"metadata\": {\n \"productName\": \"Algo.ai\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.spotflow.co/api/v1/payments/initialize")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reference\": \"string\",\n \"currency\": \"USD\",\n \"customer\": {\n \"email\": \"john@example.com\"\n },\n \"amount\": 5,\n \"expiresIn\": 10,\n \"planId\": \"95eb086a-b11a-44b2-8422-a1955ca0fd9a\",\n \"applyDiscount\": \"true OR false\",\n \"countryCode\": \"CI\",\n \"localCurrency\": \"NGN\",\n \"callBackUrl\": \"https://yourapp.com/callback\",\n \"metadata\": {\n \"productName\": \"Algo.ai\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.spotflow.co/api/v1/payments/initialize")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reference\": \"string\",\n \"currency\": \"USD\",\n \"customer\": {\n \"email\": \"john@example.com\"\n },\n \"amount\": 5,\n \"expiresIn\": 10,\n \"planId\": \"95eb086a-b11a-44b2-8422-a1955ca0fd9a\",\n \"applyDiscount\": \"true OR false\",\n \"countryCode\": \"CI\",\n \"localCurrency\": \"NGN\",\n \"callBackUrl\": \"https://yourapp.com/callback\",\n \"metadata\": {\n \"productName\": \"Algo.ai\"\n }\n}"
response = http.request(request)
puts response.read_body{
"reference": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"checkoutUrl": "https://checkout.spotflow.co/paymentCode",
"paymentCode": "PAY123456789",
"status": "pending",
"mode": "TEST",
"expiryTime": "2025-11-03T10:16:26.948278058",
"callBackUrl": "https://yourapp.com/callback",
"metadata": {
"productName": "Algo.ai"
}
}{
"error": "Missing Parameter",
"message": "missing_parameter",
"status": 400
}{
"error": "Unauthorized",
"message": "invalid_credentials",
"status": 401
}Adding Test Funds
Mobile Money
channel is set to mobile_money and a planId is included, Spotflow will automatically send a mandate approval request to the customer’s phone. The subscription will only activate once the mandate is approved.See the full guide on Mobile Money Subscriptions.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Specify a unique reference ID generated by your company to identify each customer.
"string"
Select the currency for the payment charge. Can either be in USD or in the local currency of your collection region. If you put in USD, you have to put in the local currency of the region in the local currency request field.
USD, NGN, GHS, KES, ZAR, TZS, XOF, XAF "USD"
The customer’s email address
Show child attributes
Show child attributes
The amount in the major unit of the currency, decimals allowed. For example 5.00 with currency GHS means five Ghana cedis, not five pesewas. This is not needed if you use a planId in your request.
5
The default maximum expiry time is 30 mins. However, you can set yours to the time you desire. The least time you can set is 5 mins.
10
*Note that including this turns the payment into a subscription. Omitting it makes it a one-time charge as it is used when paying for a subscription plan.
"95eb086a-b11a-44b2-8422-a1955ca0fd9a"
"true OR false"
Note that, this is only needed to be passed or used for XOF and XAF currency payments. Country code of XOF countries like Cote D'voire with code CI, or XAF countries like Cameroon with code CM.
"CI"
This is the local currency of your region. Used only when currency is set to USD. According to the local region, this can either be in NGN, GHS, ZAR, TZS, KSH etc.
NGN, GHS, KES, ZAR, TZS "NGN"
This is the URL you want your users to be redirected to after making payments. You can also set this permanently on your Spotflow dashboard.
"https://yourapp.com/callback"
This is information pertaining to additional details about your product or service. Under metadata, you have productName” as a field — This is necessary for you to add as it indicates the name of your product and helps to specify to your user what your product is called. You can add any other additional field as you deem fit.
Show child attributes
Show child attributes
Response
A JSON array of initialize payment objects.
"https://checkout.spotflow.co/paymentCode"
"PAY123456789"
"pending"
"TEST"
"2025-11-03T10:16:26.948278058"
"https://yourapp.com/callback"
This is information pertaining to additional details about your product or service.
Show child attributes
Show child attributes

