Create Customer Account
curl --request POST \
--url https://api-production.fossapay.com/api/v1/customers \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '
{
"firstName": "<string>",
"lastName": "<string>",
"middleName": "<string>",
"emailAddress": "<string>",
"mobileNumber": "<string>",
"dob": "<string>",
"address": "<string>",
"city": "<string>",
"country": "<string>",
"type": "<string>"
}
'import requests
url = "https://api-production.fossapay.com/api/v1/customers"
payload = {
"firstName": "<string>",
"lastName": "<string>",
"middleName": "<string>",
"emailAddress": "<string>",
"mobileNumber": "<string>",
"dob": "<string>",
"address": "<string>",
"city": "<string>",
"country": "<string>",
"type": "<string>"
}
headers = {
"x-api-key": "<x-api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
firstName: '<string>',
lastName: '<string>',
middleName: '<string>',
emailAddress: '<string>',
mobileNumber: '<string>',
dob: '<string>',
address: '<string>',
city: '<string>',
country: '<string>',
type: '<string>'
})
};
fetch('https://api-production.fossapay.com/api/v1/customers', 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",
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([
'firstName' => '<string>',
'lastName' => '<string>',
'middleName' => '<string>',
'emailAddress' => '<string>',
'mobileNumber' => '<string>',
'dob' => '<string>',
'address' => '<string>',
'city' => '<string>',
'country' => '<string>',
'type' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <x-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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-production.fossapay.com/api/v1/customers"
payload := strings.NewReader("{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"middleName\": \"<string>\",\n \"emailAddress\": \"<string>\",\n \"mobileNumber\": \"<string>\",\n \"dob\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<x-api-key>")
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-production.fossapay.com/api/v1/customers")
.header("x-api-key", "<x-api-key>")
.header("Content-Type", "application/json")
.body("{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"middleName\": \"<string>\",\n \"emailAddress\": \"<string>\",\n \"mobileNumber\": \"<string>\",\n \"dob\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-production.fossapay.com/api/v1/customers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"middleName\": \"<string>\",\n \"emailAddress\": \"<string>\",\n \"mobileNumber\": \"<string>\",\n \"dob\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"statusCode": 201,
"message": "Customer created successfully",
"data": {
"id": "ch2eda1f-e2a3-47ac-b8de-3149a3fb7esf",
"firstName": "John",
"lastName": "Henry",
"middleName": "Doe",
"emailAddress": "john.doe@gmail.com",
"mobileNumber": "09184728251",
"dob": "1991-08-15",
"address": "12 customer rd.",
"customerType": "individual",
"businessId": "x93f9867-e4b3-24da-9d1e-aax032bf7a3a",
"createdAt": "2026-01-08T21:39:52+01:00"
}
}
{
"status": "error",
"statusCode": 400,
"message": "error"
}
Customers
Create Customer Account
Create a new customer account
POST
/
api
/
v1
/
customers
Create Customer Account
curl --request POST \
--url https://api-production.fossapay.com/api/v1/customers \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '
{
"firstName": "<string>",
"lastName": "<string>",
"middleName": "<string>",
"emailAddress": "<string>",
"mobileNumber": "<string>",
"dob": "<string>",
"address": "<string>",
"city": "<string>",
"country": "<string>",
"type": "<string>"
}
'import requests
url = "https://api-production.fossapay.com/api/v1/customers"
payload = {
"firstName": "<string>",
"lastName": "<string>",
"middleName": "<string>",
"emailAddress": "<string>",
"mobileNumber": "<string>",
"dob": "<string>",
"address": "<string>",
"city": "<string>",
"country": "<string>",
"type": "<string>"
}
headers = {
"x-api-key": "<x-api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
firstName: '<string>',
lastName: '<string>',
middleName: '<string>',
emailAddress: '<string>',
mobileNumber: '<string>',
dob: '<string>',
address: '<string>',
city: '<string>',
country: '<string>',
type: '<string>'
})
};
fetch('https://api-production.fossapay.com/api/v1/customers', 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",
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([
'firstName' => '<string>',
'lastName' => '<string>',
'middleName' => '<string>',
'emailAddress' => '<string>',
'mobileNumber' => '<string>',
'dob' => '<string>',
'address' => '<string>',
'city' => '<string>',
'country' => '<string>',
'type' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <x-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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-production.fossapay.com/api/v1/customers"
payload := strings.NewReader("{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"middleName\": \"<string>\",\n \"emailAddress\": \"<string>\",\n \"mobileNumber\": \"<string>\",\n \"dob\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<x-api-key>")
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-production.fossapay.com/api/v1/customers")
.header("x-api-key", "<x-api-key>")
.header("Content-Type", "application/json")
.body("{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"middleName\": \"<string>\",\n \"emailAddress\": \"<string>\",\n \"mobileNumber\": \"<string>\",\n \"dob\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-production.fossapay.com/api/v1/customers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"middleName\": \"<string>\",\n \"emailAddress\": \"<string>\",\n \"mobileNumber\": \"<string>\",\n \"dob\": \"<string>\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"statusCode": 201,
"message": "Customer created successfully",
"data": {
"id": "ch2eda1f-e2a3-47ac-b8de-3149a3fb7esf",
"firstName": "John",
"lastName": "Henry",
"middleName": "Doe",
"emailAddress": "john.doe@gmail.com",
"mobileNumber": "09184728251",
"dob": "1991-08-15",
"address": "12 customer rd.",
"customerType": "individual",
"businessId": "x93f9867-e4b3-24da-9d1e-aax032bf7a3a",
"createdAt": "2026-01-08T21:39:52+01:00"
}
}
{
"status": "error",
"statusCode": 400,
"message": "error"
}
Request
Your API key for authentication
First name of the customer
Last name of the customer
Middle name of the customer
Email address of the customer
Mobile number of the customer
Date of birth in YYYY-MM-DD format (e.g., 1990-08-15)
Address of the customer
City of the customer
Country of the customer
Customer Account type
Request Example
curl -X POST https://api-production.fossapay.com/api/v1/customers \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"firstName": "John",
"lastName": "Doe",
"middleName": "Michael",
"emailAddress": "john.doe@example.com",
"mobileNumber": "+2348012345678",
"dob": "1990-08-15",
"address": "123 Main Street",
"city": "Lagos",
"country": "Nigeria",
"type": "individual"
}'
const response = await fetch('https://api-production.fossapay.com/api/v1/customers', {
method: 'POST',
headers: {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
firstName: 'John',
lastName: 'Doe',
middleName: 'Michael',
emailAddress: 'john.doe@example.com',
mobileNumber: '+2348012345678',
dob: '1990-08-15',
address: '123 Main Street',
city: 'Lagos',
country: 'Nigeria',
type: 'individual'
})
});
const customer = await response.json();
console.log(customer);
import requests
headers = {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
}
data = {
'firstName': 'John',
'lastName': 'Doe',
'middleName': 'Michael',
'emailAddress': 'john.doe@example.com',
'mobileNumber': '+2348012345678',
'dob': '1990-08-15',
'address': '123 Main Street',
'city': 'Lagos',
'country': 'Nigeria',
'type': 'individual'
}
response = requests.post('https://api-production.fossapay.com/api/v1/customers', headers=headers, json=data)
customer = response.json()
print(customer)
Response
Response status:
success or errorHTTP status code (201 for successful creation)
Human-readable response message
Show properties
Show properties
Unique identifier for the customer
Customer’s first name
Customer’s last name
Customer’s middle name
Customer’s email address
Customer’s mobile number
Customer’s date of birth
Customer’s address
Customer account type
Associated business identifier
Customer creation timestamp (ISO 8601)
Response Example
{
"status": "success",
"statusCode": 201,
"message": "Customer created successfully",
"data": {
"id": "ch2eda1f-e2a3-47ac-b8de-3149a3fb7esf",
"firstName": "John",
"lastName": "Henry",
"middleName": "Doe",
"emailAddress": "john.doe@gmail.com",
"mobileNumber": "09184728251",
"dob": "1991-08-15",
"address": "12 customer rd.",
"customerType": "individual",
"businessId": "x93f9867-e4b3-24da-9d1e-aax032bf7a3a",
"createdAt": "2026-01-08T21:39:52+01:00"
}
}
{
"status": "error",
"statusCode": 400,
"message": "error"
}
Error Codes
| Code | Description |
|---|---|
INVALID_EMAIL | Email address is invalid |
INVALID_PHONE | Phone number is invalid |
INVALID_DOB | Date of birth format is invalid |
MISSING_REQUIRED_FIELD | Required field is missing |
INVALID_CUSTOMER_TYPE | Customer type is invalid |
Rate Limit: 100 requests per minute
Store the
customer_id in your database for future reference and customer management.⌘I

