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>",
"dateOfBirth": "<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>",
"dateOfBirth": "<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>',
dateOfBirth: '<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>',
'dateOfBirth' => '<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 \"dateOfBirth\": \"<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 \"dateOfBirth\": \"<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 \"dateOfBirth\": \"<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",
"dateOfBirth": "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>",
"dateOfBirth": "<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>",
"dateOfBirth": "<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>',
dateOfBirth: '<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>',
'dateOfBirth' => '<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 \"dateOfBirth\": \"<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 \"dateOfBirth\": \"<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 \"dateOfBirth\": \"<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",
"dateOfBirth": "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
string
required
Your API key for authentication
string
required
First name of the customer
string
required
Last name of the customer
string
Middle name of the customer
string
required
Email address of the customer
string
required
Mobile number of the customer
string
required
Date of birth in YYYY-MM-DD format (e.g., 1990-08-15)
string
required
Address of the customer
string
required
City of the customer
string
required
Country of the customer
string
required
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",
"dateOfBirth": "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',
dateOfBirth: '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',
'dateOfBirth': '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
string
Response status:
success or errornumber
HTTP status code (201 for successful creation)
string
Human-readable response message
object
Show properties
Show properties
string
Unique identifier for the customer
string
Customer’s first name
string
Customer’s last name
string
Customer’s middle name
string
Customer’s email address
string
Customer’s mobile number
string
Customer’s date of birth
string
Customer’s address
string
Customer account type
string
Associated business identifier
string
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",
"dateOfBirth": "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.
