Get customer by ID
curl --request GET \
--url https://api-production.fossapay.com/api/v1/customers/{customerId} \
--header 'x-api-key: <api-key>'import requests
url = "https://api-production.fossapay.com/api/v1/customers/{customerId}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api-production.fossapay.com/api/v1/customers/{customerId}', 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-production.fossapay.com/api/v1/customers/{customerId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-production.fossapay.com/api/v1/customers/{customerId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api-production.fossapay.com/api/v1/customers/{customerId}")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-production.fossapay.com/api/v1/customers/{customerId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"status": "success",
"statusCode": 200,
"message": "Customer retrieved successfully",
"data": {
"id": "11111111-1111-4111-8111-111111111111",
"businessId": "22222222-2222-4222-8222-222222222222",
"firstName": "John",
"lastName": "Doe",
"middleName": "Michael",
"emailAddress": "john.doe@example.com",
"mobileNumber": "+2348012345678",
"dob": "1990-08-15",
"customerType": "individual",
"address": "123 Example Street",
"city": "Lagos",
"createdAt": "2021-01-08T21:39:52+01:00"
}
}
{
"status": "error",
"statusCode": 401,
"message": "Invalid API key"
}
{
"status": "error",
"statusCode": 404,
"message": "Customer not found"
}
Customers
Get Customer by ID
Retrieve a merchant-owned customer by UUID
GET
/
api
/
v1
/
customers
/
{customerId}
Get customer by ID
curl --request GET \
--url https://api-production.fossapay.com/api/v1/customers/{customerId} \
--header 'x-api-key: <api-key>'import requests
url = "https://api-production.fossapay.com/api/v1/customers/{customerId}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api-production.fossapay.com/api/v1/customers/{customerId}', 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-production.fossapay.com/api/v1/customers/{customerId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-production.fossapay.com/api/v1/customers/{customerId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api-production.fossapay.com/api/v1/customers/{customerId}")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-production.fossapay.com/api/v1/customers/{customerId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"status": "success",
"statusCode": 200,
"message": "Customer retrieved successfully",
"data": {
"id": "11111111-1111-4111-8111-111111111111",
"businessId": "22222222-2222-4222-8222-222222222222",
"firstName": "John",
"lastName": "Doe",
"middleName": "Michael",
"emailAddress": "john.doe@example.com",
"mobileNumber": "+2348012345678",
"dob": "1990-08-15",
"customerType": "individual",
"address": "123 Example Street",
"city": "Lagos",
"createdAt": "2021-01-08T21:39:52+01:00"
}
}
{
"status": "error",
"statusCode": 401,
"message": "Invalid API key"
}
{
"status": "error",
"statusCode": 404,
"message": "Customer not found"
}
Overview
Retrieve detailed information about a specific customer using their unique customer ID.Request
string
required
Your API key for authentication
string
required
FossaPay customer UUID. The customer must belong to the authenticated merchant.
Response
string
Response status:
success or errornumber
HTTP status code (200 for successful retrieval)
string
Human-readable response message
object
Customer object
Response Example
{
"status": "success",
"statusCode": 200,
"message": "Customer retrieved successfully",
"data": {
"id": "11111111-1111-4111-8111-111111111111",
"businessId": "22222222-2222-4222-8222-222222222222",
"firstName": "John",
"lastName": "Doe",
"middleName": "Michael",
"emailAddress": "john.doe@example.com",
"mobileNumber": "+2348012345678",
"dob": "1990-08-15",
"customerType": "individual",
"address": "123 Example Street",
"city": "Lagos",
"createdAt": "2021-01-08T21:39:52+01:00"
}
}
{
"status": "error",
"statusCode": 401,
"message": "Invalid API key"
}
{
"status": "error",
"statusCode": 404,
"message": "Customer not found"
}
Example
- cURL
- Node.js
curl -X GET https://api-production.fossapay.com/api/v1/customers/11111111-1111-4111-8111-111111111111 \
-H "x-api-key: $FOSSAPAY_API_KEY"
const customerId = "11111111-1111-4111-8111-111111111111";
const response = await fetch(
`https://api-production.fossapay.com/api/v1/customers/${customerId}`,
{
method: "GET",
headers: {
"x-api-key": process.env.FOSSAPAY_API_KEY,
},
},
);
const customer = await response.json();
if (!response.ok) throw new Error(customer.message);
Errors
| Status | Typical cause |
|---|---|
401 | Missing or invalid API key |
404 | Customer UUID was not found for the authenticated merchant |
Customer access is merchant-scoped. Persist the returned customer UUID with your own user identifier.

