Create a new customer account
curl --request POST \
--url https://api-production.fossapay.com/api/v1/customers \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"firstName": "<string>",
"lastName": "<string>",
"emailAddress": "jsmith@example.com",
"mobileNumber": "<string>",
"dateOfBirth": "2023-12-25",
"address": "<string>",
"city": "<string>",
"country": "<string>",
"type": "individual",
"middleName": "<string>",
"metadata": {}
}
'import requests
url = "https://api-production.fossapay.com/api/v1/customers"
payload = {
"firstName": "<string>",
"lastName": "<string>",
"emailAddress": "jsmith@example.com",
"mobileNumber": "<string>",
"dateOfBirth": "2023-12-25",
"address": "<string>",
"city": "<string>",
"country": "<string>",
"type": "individual",
"middleName": "<string>",
"metadata": {}
}
headers = {
"x-api-key": "<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': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
firstName: '<string>',
lastName: '<string>',
emailAddress: 'jsmith@example.com',
mobileNumber: '<string>',
dateOfBirth: '2023-12-25',
address: '<string>',
city: '<string>',
country: '<string>',
type: 'individual',
middleName: '<string>',
metadata: {}
})
};
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>',
'emailAddress' => 'jsmith@example.com',
'mobileNumber' => '<string>',
'dateOfBirth' => '2023-12-25',
'address' => '<string>',
'city' => '<string>',
'country' => '<string>',
'type' => 'individual',
'middleName' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"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 \"emailAddress\": \"jsmith@example.com\",\n \"mobileNumber\": \"<string>\",\n \"dateOfBirth\": \"2023-12-25\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"individual\",\n \"middleName\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<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", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"emailAddress\": \"jsmith@example.com\",\n \"mobileNumber\": \"<string>\",\n \"dateOfBirth\": \"2023-12-25\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"individual\",\n \"middleName\": \"<string>\",\n \"metadata\": {}\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"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"emailAddress\": \"jsmith@example.com\",\n \"mobileNumber\": \"<string>\",\n \"dateOfBirth\": \"2023-12-25\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"individual\",\n \"middleName\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"statusCode": 201,
"message": "Customer created successfully",
"data": {
"id": "11111111-1111-4111-8111-111111111111",
"firstName": "John",
"lastName": "Doe",
"middleName": "Michael",
"emailAddress": "john.doe@example.com",
"mobileNumber": "+2348012345678",
"dob": "1990-08-15",
"address": "123 Example Street",
"customerType": "individual",
"businessId": "22222222-2222-4222-8222-222222222222",
"createdAt": "2026-01-08T21:39:52+01:00"
}
}
{
"status": "error",
"statusCode": 422,
"message": "type must be 'individual'"
}
Customers
Create Customer Account
Create an individual customer owned by the authenticated merchant
POST
/
api
/
v1
/
customers
Create a new customer account
curl --request POST \
--url https://api-production.fossapay.com/api/v1/customers \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"firstName": "<string>",
"lastName": "<string>",
"emailAddress": "jsmith@example.com",
"mobileNumber": "<string>",
"dateOfBirth": "2023-12-25",
"address": "<string>",
"city": "<string>",
"country": "<string>",
"type": "individual",
"middleName": "<string>",
"metadata": {}
}
'import requests
url = "https://api-production.fossapay.com/api/v1/customers"
payload = {
"firstName": "<string>",
"lastName": "<string>",
"emailAddress": "jsmith@example.com",
"mobileNumber": "<string>",
"dateOfBirth": "2023-12-25",
"address": "<string>",
"city": "<string>",
"country": "<string>",
"type": "individual",
"middleName": "<string>",
"metadata": {}
}
headers = {
"x-api-key": "<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': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
firstName: '<string>',
lastName: '<string>',
emailAddress: 'jsmith@example.com',
mobileNumber: '<string>',
dateOfBirth: '2023-12-25',
address: '<string>',
city: '<string>',
country: '<string>',
type: 'individual',
middleName: '<string>',
metadata: {}
})
};
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>',
'emailAddress' => 'jsmith@example.com',
'mobileNumber' => '<string>',
'dateOfBirth' => '2023-12-25',
'address' => '<string>',
'city' => '<string>',
'country' => '<string>',
'type' => 'individual',
'middleName' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"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 \"emailAddress\": \"jsmith@example.com\",\n \"mobileNumber\": \"<string>\",\n \"dateOfBirth\": \"2023-12-25\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"individual\",\n \"middleName\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<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", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"emailAddress\": \"jsmith@example.com\",\n \"mobileNumber\": \"<string>\",\n \"dateOfBirth\": \"2023-12-25\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"individual\",\n \"middleName\": \"<string>\",\n \"metadata\": {}\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"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"firstName\": \"<string>\",\n \"lastName\": \"<string>\",\n \"emailAddress\": \"jsmith@example.com\",\n \"mobileNumber\": \"<string>\",\n \"dateOfBirth\": \"2023-12-25\",\n \"address\": \"<string>\",\n \"city\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"individual\",\n \"middleName\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"statusCode": 201,
"message": "Customer created successfully",
"data": {
"id": "11111111-1111-4111-8111-111111111111",
"firstName": "John",
"lastName": "Doe",
"middleName": "Michael",
"emailAddress": "john.doe@example.com",
"mobileNumber": "+2348012345678",
"dob": "1990-08-15",
"address": "123 Example Street",
"customerType": "individual",
"businessId": "22222222-2222-4222-8222-222222222222",
"createdAt": "2026-01-08T21:39:52+01:00"
}
}
{
"status": "error",
"statusCode": 422,
"message": "type must be 'individual'"
}
Request
string
required
Active production API key belonging to the merchant that will own the customer.
string
required
Exactly one given name. Spaces and numbers are not accepted.
string
required
Exactly one family name. Spaces and numbers are not accepted.
string
Optional single middle name. Do not combine multiple names in this field.
string
required
Non-empty email address. It must be unique within the authenticated merchant.
string
required
Non-empty mobile number retained by FossaPay.
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. The only accepted value is
individual; other values return HTTP 422 before provider processing.Request Example
curl -X POST https://api-production.fossapay.com/api/v1/customers \
-H "x-api-key: $FOSSAPAY_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 Example 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': process.env.FOSSAPAY_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 Example Street',
city: 'Lagos',
country: 'Nigeria',
type: 'individual'
})
});
const customer = await response.json();
if (!response.ok) throw new Error(customer.message);
import requests
headers = {
'x-api-key': process.env.FOSSAPAY_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 Example 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()
response.raise_for_status()
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": "11111111-1111-4111-8111-111111111111",
"firstName": "John",
"lastName": "Doe",
"middleName": "Michael",
"emailAddress": "john.doe@example.com",
"mobileNumber": "+2348012345678",
"dob": "1990-08-15",
"address": "123 Example Street",
"customerType": "individual",
"businessId": "22222222-2222-4222-8222-222222222222",
"createdAt": "2026-01-08T21:39:52+01:00"
}
}
{
"status": "error",
"statusCode": 422,
"message": "type must be 'individual'"
}
Errors
| Status | Typical cause |
|---|---|
400 | Duplicate email, unsupported country, or downstream customer-creation rejection |
401 | Missing or invalid API key |
422 | Missing or unknown field, invalid name, invalid date format, or type other than individual |
5xx | Temporary FossaPay or provider failure; reconcile before retrying |
Store
data.id in your database. Customer wallet and transfer operations require this UUID.Authorizations
Body
application/json

