API reference

Cardholders

A cardholder is the person a card is issued to: a member of your team or one of your customers. The card issuer verifies their identity before any card is issued.

POST/v1/cardholdersCreate a cardholder POST/v1/cardholders/{id}/verificationSubmit identity verification GET/v1/cardholders/{id}Retrieve a cardholder GET/v1/cardholdersList cardholders

The cardholder object

Attributes

idstring

Unique identifier (UUID).

livemodeboolean

true for live objects, false for test objects.

objectstring

Always cardholder.

typestring

team for your own staff, customer for your customers.

teamcustomer

first_namestring

last_namestring

emailstring

phonestring | null

International format.

countrystring

ISO 3166-1 alpha-2.

citystring | null

birth_datestring | null

YYYY-MM-DD.

id_documentstring

Identity document type.

national_idpassportdriver_licensevoters_card

id_number_last4string | null

Last 4 characters of the document number. The full number is never returned.

verificationobject

Identity verification by the card issuer. A card can only be issued once status is verified.

Show child attributes

statusstring

pendingin_reviewverifiedrejected

reasonstring | null

Why it was rejected.

verified_atstring | null

When it was verified.

created_atstring

Creation time, ISO 8601 (UTC).

updated_atstring

Last change, ISO 8601 (UTC).

The cardholder object

{
  "id": "5df6acd9-4bac-4e19-869c-fcde6b79f389",
  "object": "cardholder",
  "livemode": false,
  "type": "customer",
  "first_name": "Awa",
  "last_name": "Ndiaye",
  "email": "awa@example.com",
  "phone": "+237670000999",
  "country": "CM",
  "city": "Douala",
  "birth_date": "1991-02-03",
  "id_document": "national_id",
  "id_number_last4": "3408",
  "verification": {
    "status": "pending",
    "reason": null,
    "verified_at": null
  },
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:06.394Z"
}

Create a cardholder

POST/v1/cardholders

Creates the cardholder with verification.status pending. Then submit the identity verification.

Key roles: Owner or Finance

Body

first_namestringRequired

Up to 60 characters.

last_namestringRequired

Up to 60 characters.

emailstringRequired

Unique per business.

countrystringRequired

ISO 3166-1 alpha-2.

typestringOptionalDefault team

teamcustomer

phonestringOptional

International format. Required before verification.

citystringOptional

birth_datestringOptional

YYYY-MM-DD.

id_documentstringOptionalDefault national_id

Document used for verification.

national_idpassportdriver_licensevoters_card

id_numberstringOptional

Document number. Only its last 4 characters are returned.

addressobjectOptional

Home address, kept with the cardholder: line1, line2, city, state, postal_code. The verification asks for it again.

Returns

Returns the new cardholder object with 201.

Errors worth handling

HTTP	Code	Description
`400`	`parameter_invalid`	A parameter has the wrong type or value. See `param`.
`403`	`permission_denied`	The key’s creator does not have the role required for this operation.
`409`	`cardholder_exists`	A cardholder already uses this email.
`429`	`rate_limited`	A rate limit was reached. Wait for `Retry-After` seconds. See Rate limits.

curl https://api.monerail.com/v1/cardholders \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "customer",
    "first_name": "Awa",
    "last_name": "Ndiaye",
    "email": "awa@example.com",
    "phone": "+237670000999",
    "country": "CM",
    "city": "Douala",
    "birth_date": "1991-02-03",
    "id_document": "national_id"
  }'

const res = await fetch('https://api.monerail.com/v1/cardholders', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MONERAIL_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'customer',
    first_name: 'Awa',
    last_name: 'Ndiaye',
    email: 'awa@example.com',
    phone: '+237670000999',
    country: 'CM',
    city: 'Douala',
    birth_date: '1991-02-03',
    id_document: 'national_id',
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

import os

import requests

res = requests.post(
    "https://api.monerail.com/v1/cardholders",
    headers={"Authorization": f"Bearer {os.environ['MONERAIL_KEY']}"},
    json={
        "type": "customer",
        "first_name": "Awa",
        "last_name": "Ndiaye",
        "email": "awa@example.com",
        "phone": "+237670000999",
        "country": "CM",
        "city": "Douala",
        "birth_date": "1991-02-03",
        "id_document": "national_id",
    },
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

<?php
$ch = curl_init('https://api.monerail.com/v1/cardholders');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('MONERAIL_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'type' => 'customer',
    'first_name' => 'Awa',
    'last_name' => 'Ndiaye',
    'email' => 'awa@example.com',
    'phone' => '+237670000999',
    'country' => 'CM',
    'city' => 'Douala',
    'birth_date' => '1991-02-03',
    'id_document' => 'national_id',
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status >= 400) {
  throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
print_r($data);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	payload, err := json.Marshal(map[string]any{
		"type":        "customer",
		"first_name":  "Awa",
		"last_name":   "Ndiaye",
		"email":       "awa@example.com",
		"phone":       "+237670000999",
		"country":     "CM",
		"city":        "Douala",
		"birth_date":  "1991-02-03",
		"id_document": "national_id",
	})
	if err != nil {
		panic(err)
	}
	req, err := http.NewRequest(http.MethodPost, "https://api.monerail.com/v1/cardholders", bytes.NewReader(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("MONERAIL_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
		panic(err)
	}
	if res.StatusCode >= 400 {
		panic(fmt.Sprint(data["error"]))
	}
	fmt.Println(data)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "type": "customer",
              "first_name": "Awa",
              "last_name": "Ndiaye",
              "email": "awa@example.com",
              "phone": "+237670000999",
              "country": "CM",
              "city": "Douala",
              "birth_date": "1991-02-03",
              "id_document": "national_id"
            }
            """;
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.monerail.com/v1/cardholders"))
            .header("Authorization", "Bearer " + System.getenv("MONERAIL_KEY"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new RuntimeException(response.body());
        }
        System.out.println(response.body()); // parse with your JSON library (Jackson, Gson…)
    }
}

require "json"
require "net/http"

uri = URI("https://api.monerail.com/v1/cardholders")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch("MONERAIL_KEY")}"
req["Content-Type"] = "application/json"
req.body = JSON.generate({
  type: "customer",
  first_name: "Awa",
  last_name: "Ndiaye",
  email: "awa@example.com",
  phone: "+237670000999",
  country: "CM",
  city: "Douala",
  birth_date: "1991-02-03",
  id_document: "national_id",
})

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
raise "#{data["error"]["code"]}: #{data["error"]["message"]}" unless res.is_a?(Net::HTTPSuccess)
puts data

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MONERAIL_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.monerail.com/v1/cardholders");
request.Content = JsonContent.Create(new
{
    type = "customer",
    first_name = "Awa",
    last_name = "Ndiaye",
    email = "awa@example.com",
    phone = "+237670000999",
    country = "CM",
    city = "Douala",
    birth_date = "1991-02-03",
    id_document = "national_id",
});

using var response = await http.SendAsync(request);
var data = await response.Content.ReadFromJsonAsync<JsonElement>();
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(data.GetProperty("error").GetProperty("message").GetString());
}
Console.WriteLine(data);

Response201

{
  "id": "5df6acd9-4bac-4e19-869c-fcde6b79f389",
  "object": "cardholder",
  "livemode": false,
  "type": "customer",
  "first_name": "Awa",
  "last_name": "Ndiaye",
  "email": "awa@example.com",
  "phone": "+237670000999",
  "country": "CM",
  "city": "Douala",
  "birth_date": "1991-02-03",
  "id_document": "national_id",
  "id_number_last4": "3408",
  "verification": {
    "status": "pending",
    "reason": null,
    "verified_at": null
  },
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:06.394Z"
}

Submit identity verification

POST/v1/cardholders/{id}/verification

Sends the identity details and document images to the card issuer. Returns 202 with verification.status in_review. The decision arrives with the cardholder.kyc_updated event. After a rejection, call it again with corrected details. If the cardholder is already verified, returns 200 with no change; while a review is in progress, documents are not sent again. The first name, last name and birth date must match the document exactly. Verification is per business: a person already verified by another business is verified again for yours. Limited to 5 calls per cardholder per 24 hours.

Key roles: Owner or Finance

Path parameters

idstringRequired

ID of the cardholder.

Body

id_numberstringRequired

Document number.

birth_datestringRequired

YYYY-MM-DD.

addressobjectRequired

Home address.

Show child attributes

line1stringRequired

citystringRequired

line2stringOptional

statestringOptional

Region. Defaults to the city.

postal_codestringOptional

Optional.

documentsobjectRequired

Photos of the document, as base64 or data:image/…;base64, URIs. JPEG or PNG, 4 MB each at most. Sharp, uncropped, without glare, with the whole document visible.

Show child attributes

frontstringRequired

Front side.

backstringOptional

Back side. Required, except for a passport (front only).

place_of_birthstringRequired

City of birth, up to 80 characters.

phonestringOptional

International format, if not set on the cardholder.

Returns

Returns the cardholder object with 202: the outcome follows by webhook.

Errors worth handling

HTTP	Code	Description
`400`	`parameter_missing`	A required parameter is missing. See `param`.
`400`	`parameter_invalid`	A parameter has the wrong type or value. See `param`.
`400`	`phone_invalid`	The number cannot be read as an international number.
`403`	`permission_denied`	The key’s creator does not have the role required for this operation.
`429`	`rate_limited`	A rate limit was reached. Wait for `Retry-After` seconds. See Rate limits.

curl https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389/verification \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id_number": "CM12345678",
    "birth_date": "1991-02-03",
    "place_of_birth": "Douala",
    "address": {
      "line1": "12 rue Joss",
      "city": "Douala",
      "state": "Littoral"
    },
    "documents": {
      "front": "data:image/jpeg;base64,/9j/4AAQ…",
      "back": "data:image/jpeg;base64,/9j/4AAQ…"
    }
  }'

const res = await fetch('https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389/verification', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MONERAIL_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    id_number: 'CM12345678',
    birth_date: '1991-02-03',
    place_of_birth: 'Douala',
    address: {
      line1: '12 rue Joss',
      city: 'Douala',
      state: 'Littoral',
    },
    documents: {
      front: 'data:image/jpeg;base64,/9j/4AAQ…',
      back: 'data:image/jpeg;base64,/9j/4AAQ…',
    },
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

import os

import requests

res = requests.post(
    "https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389/verification",
    headers={"Authorization": f"Bearer {os.environ['MONERAIL_KEY']}"},
    json={
        "id_number": "CM12345678",
        "birth_date": "1991-02-03",
        "place_of_birth": "Douala",
        "address": {
            "line1": "12 rue Joss",
            "city": "Douala",
            "state": "Littoral",
        },
        "documents": {
            "front": "data:image/jpeg;base64,/9j/4AAQ…",
            "back": "data:image/jpeg;base64,/9j/4AAQ…",
        },
    },
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

<?php
$ch = curl_init('https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389/verification');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('MONERAIL_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'id_number' => 'CM12345678',
    'birth_date' => '1991-02-03',
    'place_of_birth' => 'Douala',
    'address' => [
      'line1' => '12 rue Joss',
      'city' => 'Douala',
      'state' => 'Littoral',
    ],
    'documents' => [
      'front' => 'data:image/jpeg;base64,/9j/4AAQ…',
      'back' => 'data:image/jpeg;base64,/9j/4AAQ…',
    ],
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status >= 400) {
  throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
print_r($data);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	payload, err := json.Marshal(map[string]any{
		"id_number":      "CM12345678",
		"birth_date":     "1991-02-03",
		"place_of_birth": "Douala",
		"address": map[string]any{
			"line1": "12 rue Joss",
			"city":  "Douala",
			"state": "Littoral",
		},
		"documents": map[string]any{
			"front": "data:image/jpeg;base64,/9j/4AAQ…",
			"back":  "data:image/jpeg;base64,/9j/4AAQ…",
		},
	})
	if err != nil {
		panic(err)
	}
	req, err := http.NewRequest(http.MethodPost, "https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389/verification", bytes.NewReader(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("MONERAIL_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
		panic(err)
	}
	if res.StatusCode >= 400 {
		panic(fmt.Sprint(data["error"]))
	}
	fmt.Println(data)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "id_number": "CM12345678",
              "birth_date": "1991-02-03",
              "place_of_birth": "Douala",
              "address": {
                "line1": "12 rue Joss",
                "city": "Douala",
                "state": "Littoral"
              },
              "documents": {
                "front": "data:image/jpeg;base64,/9j/4AAQ…",
                "back": "data:image/jpeg;base64,/9j/4AAQ…"
              }
            }
            """;
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389/verification"))
            .header("Authorization", "Bearer " + System.getenv("MONERAIL_KEY"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new RuntimeException(response.body());
        }
        System.out.println(response.body()); // parse with your JSON library (Jackson, Gson…)
    }
}

require "json"
require "net/http"

uri = URI("https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389/verification")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch("MONERAIL_KEY")}"
req["Content-Type"] = "application/json"
req.body = JSON.generate({
  id_number: "CM12345678",
  birth_date: "1991-02-03",
  place_of_birth: "Douala",
  address: {
    line1: "12 rue Joss",
    city: "Douala",
    state: "Littoral",
  },
  documents: {
    front: "data:image/jpeg;base64,/9j/4AAQ…",
    back: "data:image/jpeg;base64,/9j/4AAQ…",
  },
})

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
raise "#{data["error"]["code"]}: #{data["error"]["message"]}" unless res.is_a?(Net::HTTPSuccess)
puts data

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MONERAIL_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389/verification");
request.Content = JsonContent.Create(new
{
    id_number = "CM12345678",
    birth_date = "1991-02-03",
    place_of_birth = "Douala",
    address = new
    {
        line1 = "12 rue Joss",
        city = "Douala",
        state = "Littoral",
    },
    documents = new
    {
        front = "data:image/jpeg;base64,/9j/4AAQ…",
        back = "data:image/jpeg;base64,/9j/4AAQ…",
    },
});

using var response = await http.SendAsync(request);
var data = await response.Content.ReadFromJsonAsync<JsonElement>();
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(data.GetProperty("error").GetProperty("message").GetString());
}
Console.WriteLine(data);

Response202

{
  "id": "5df6acd9-4bac-4e19-869c-fcde6b79f389",
  "object": "cardholder",
  "livemode": false,
  "type": "customer",
  "first_name": "Awa",
  "last_name": "Ndiaye",
  "email": "awa@example.com",
  "phone": "+237670000999",
  "country": "CM",
  "city": "Douala",
  "birth_date": "1991-02-03",
  "id_document": "national_id",
  "id_number_last4": "3408",
  "verification": {
    "status": "in_review",
    "reason": null,
    "verified_at": null
  },
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:09.807Z"
}

Retrieve a cardholder

GET/v1/cardholders/{id}

Key roles: Every role

Path parameters

idstringRequired

ID of the cardholder.

Returns

Returns the cardholder object.

curl https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389 \
  -H "Authorization: Bearer $MONERAIL_KEY"

const res = await fetch('https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389', {
  headers: {
    Authorization: `Bearer ${process.env.MONERAIL_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

import os

import requests

res = requests.get(
    "https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389",
    headers={"Authorization": f"Bearer {os.environ['MONERAIL_KEY']}"},
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

<?php
$ch = curl_init('https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('MONERAIL_KEY'),
  ],
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status >= 400) {
  throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
print_r($data);

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("MONERAIL_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
		panic(err)
	}
	if res.StatusCode >= 400 {
		panic(fmt.Sprint(data["error"]))
	}
	fmt.Println(data)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389"))
            .header("Authorization", "Bearer " + System.getenv("MONERAIL_KEY"))
            .GET()
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new RuntimeException(response.body());
        }
        System.out.println(response.body()); // parse with your JSON library (Jackson, Gson…)
    }
}

require "json"
require "net/http"

uri = URI("https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch("MONERAIL_KEY")}"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
raise "#{data["error"]["code"]}: #{data["error"]["message"]}" unless res.is_a?(Net::HTTPSuccess)
puts data

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MONERAIL_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.monerail.com/v1/cardholders/5df6acd9-4bac-4e19-869c-fcde6b79f389");

using var response = await http.SendAsync(request);
var data = await response.Content.ReadFromJsonAsync<JsonElement>();
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(data.GetProperty("error").GetProperty("message").GetString());
}
Console.WriteLine(data);

Response200

{
  "id": "5df6acd9-4bac-4e19-869c-fcde6b79f389",
  "object": "cardholder",
  "livemode": false,
  "type": "customer",
  "first_name": "Awa",
  "last_name": "Ndiaye",
  "email": "awa@example.com",
  "phone": "+237670000999",
  "country": "CM",
  "city": "Douala",
  "birth_date": "1991-02-03",
  "id_document": "national_id",
  "id_number_last4": "3408",
  "verification": {
    "status": "verified",
    "reason": null,
    "verified_at": "2026-10-30T13:47:09.807Z"
  },
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:06.394Z"
}

List cardholders

GET/v1/cardholders

Newest first.

Key roles: Every role

Query parameters

limitintegerOptionalDefault 20

Number of objects to return, 1 to 100.

starting_afterstringOptional

Cursor: the ID of the last object of the previous page.

Returns

Returns a list object: data holds up to limit cardholder objects, and has_more tells whether more follow.

curl "https://api.monerail.com/v1/cardholders?limit=10" \
  -H "Authorization: Bearer $MONERAIL_KEY"

const res = await fetch('https://api.monerail.com/v1/cardholders?limit=10', {
  headers: {
    Authorization: `Bearer ${process.env.MONERAIL_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

import os

import requests

res = requests.get(
    "https://api.monerail.com/v1/cardholders",
    headers={"Authorization": f"Bearer {os.environ['MONERAIL_KEY']}"},
    params={"limit": 10},
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

<?php
$ch = curl_init('https://api.monerail.com/v1/cardholders?limit=10');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('MONERAIL_KEY'),
  ],
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status >= 400) {
  throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
print_r($data);

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://api.monerail.com/v1/cardholders?limit=10", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("MONERAIL_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var data map[string]any
	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
		panic(err)
	}
	if res.StatusCode >= 400 {
		panic(fmt.Sprint(data["error"]))
	}
	fmt.Println(data)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.monerail.com/v1/cardholders?limit=10"))
            .header("Authorization", "Bearer " + System.getenv("MONERAIL_KEY"))
            .GET()
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new RuntimeException(response.body());
        }
        System.out.println(response.body()); // parse with your JSON library (Jackson, Gson…)
    }
}

require "json"
require "net/http"

uri = URI("https://api.monerail.com/v1/cardholders?limit=10")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch("MONERAIL_KEY")}"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
raise "#{data["error"]["code"]}: #{data["error"]["message"]}" unless res.is_a?(Net::HTTPSuccess)
puts data

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MONERAIL_KEY"));

using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.monerail.com/v1/cardholders?limit=10");

using var response = await http.SendAsync(request);
var data = await response.Content.ReadFromJsonAsync<JsonElement>();
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(data.GetProperty("error").GetProperty("message").GetString());
}
Console.WriteLine(data);

Response200

{
  "object": "list",
  "url": "/v1/cardholders",
  "data": [
    {
      "id": "5df6acd9-4bac-4e19-869c-fcde6b79f389",
      "object": "cardholder",
      "livemode": false,
      "type": "customer",
      "first_name": "Awa",
      "last_name": "Ndiaye",
      "email": "awa@example.com",
      "phone": "+237670000999",
      "country": "CM",
      "city": "Douala",
      "birth_date": "1991-02-03",
      "id_document": "national_id",
      "id_number_last4": "3408",
      "verification": {
        "status": "pending",
        "reason": null,
        "verified_at": null
      },
      "created_at": "2026-10-30T13:47:06.394Z",
      "updated_at": "2026-10-30T13:47:06.394Z"
    }
  ],
  "has_more": false
}

Cardholders

The cardholder object#

Attributes

Create a cardholder#

Body

Returns

Errors worth handling

Submit identity verification#

Path parameters

Body

Returns

Errors worth handling

Retrieve a cardholder#

Path parameters

Returns

List cardholders#

Query parameters

Returns

The cardholder object

Create a cardholder

Submit identity verification

Retrieve a cardholder

List cardholders