API Documentation

Explore our REST API ecosystem designed for seamless integration into enterprise and fintech workflows. The Citicapitol Bank API suite empowers developers to orchestrate complex financial operations programmatically, including payouts, collections, reconciliations, and real-time transaction monitoring. Built with RESTful principles and secured using OAuth2 authentication standards, our APIs provide granular access control, ensuring that each key and endpoint operates within your assigned permission scope. Leverage sandbox environments for comprehensive testing, simulate high-volume transaction scenarios, and validate responses before production deployment. Our endpoints return consistent, versioned JSON payloads, with well-defined status codes, rate-limiting headers, and webhook callbacks for asynchronous event handling, enabling your systems to maintain synchronization with Citicapitol's core banking infrastructure. Whether integrating ERP platforms, e-commerce solutions, or custom financial applications, our APIs are engineered to deliver high availability, low latency, and enterprise-grade security standards, allowing your organization to innovate confidently in payments and treasury management.

Authentication

All Citicapitol Bank API requests must include your issued API key as a Bearer token. This key uniquely identifies the system making the request and must be kept secure. For production use, ensure that API keys are stored in encrypted environment variables and never committed directly into source code repositories. Unauthorized or malformed requests will be rejected with a 401 Unauthorized error.

API keys are tied to your business account and permissions. Meaning that if your account only has payout permissions, methods like collections will return an access error. You may issue multiple keys for different environments such as local development, staging, or production, allowing you to revoke any compromised or inactive access tokens without impacting other systems.


curl -X GET "https://api.citicapitol.com/v1/balance" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json"


import fetch from "node-fetch";

const response = await fetch(
  "https://api.citicapitol.com/v1/balance",
  {
    headers: {
      "Authorization": "Bearer <YOUR_API_KEY>",
      "Content-Type": "application/json"
    }
  }
);

console.log(await response.json());


$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.citicapitol.com/v1/balance");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer <YOUR_API_KEY>",
  "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

print_r($response);


import requests

response = requests.get(
  "https://api.citicapitol.com/v1/balance",
  headers={
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json"
  }
)

print(response.json())

OAuth2 — Client Credentials (Machine-to-Machine)

For enterprise integrations we recommend the OAuth2 Client Credentials grant. Your application exchanges a client_id and client_secret for a short-lived access token (JWT). This avoids storing long-lived static keys in code.

Tokens include scopes that restrict actions (e.g., payouts:write, reconciliation:read). Rotate client secrets periodically and use mutual TLS for increased security if your operations require it.

Token Request


POST https://auth.citicapitol.com/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "scope": "payouts:write reconciliation:read"
}

Token Response


{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "payouts:write reconciliation:read"
}

Use the returned access_token in the Authorization header for subsequent API calls. The token expiry is short (typically 1 hour), so your app should refresh periodically.


curl -X POST "https://auth.citicapitol.com/oauth/token" \
-H "Content-Type: application/json" \
-d '{
  "grant_type":"client_credentials",
  "client_id":"your-client-id",
  "client_secret":"your-client-secret",
  "scope":"payouts:write reconciliation:read"
}'


import fetch from "node-fetch";

const res = await fetch("https://auth.citicapitol.com/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "client_credentials",
    client_id: "your-client-id",
    client_secret: "your-client-secret",
    scope: "payouts:write reconciliation:read"
  })
});
console.log(await res.json());


$payload = [
  "grant_type" => "client_credentials",
  "client_id" => "your-client-id",
  "client_secret" => "your-client-secret",
  "scope" => "payouts:write reconciliation:read"
];

$ch = curl_init("https://auth.citicapitol.com/oauth/token");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($ch);
curl_close($ch);
print_r(json_decode($res, true));


import requests

res = requests.post("https://auth.citicapitol.com/oauth/token",
    json={
        "grant_type":"client_credentials",
        "client_id":"your-client-id",
        "client_secret":"your-client-secret",
        "scope":"payouts:write reconciliation:read"
    })
print(res.json())

POST /v1/payouts

This endpoint allows businesses to initiate payouts to beneficiary bank accounts. Once a payout request is submitted, Citicapitol Bank validates the request parameters, verifies available balance, applies fraud-screening heuristics, and places the transaction in the processing pipeline.

Depending on your account configuration, payouts may process instantly, batched in settlement cycles, or require manual approval from your operations dashboard. If the payout is delayed, intermediate statuses such as pending_approval or queued may be returned. Failed payouts will contain error metadata that can be reviewed in the dashboard or via the Reconciliation API.

Request Body


{
  "account_id": "acct_123",
  "amount": 1000,
  "currency": "USD",
  "reference": "Invoice #456"
}

Response


{
  "transaction_id": "txn_abc123",
  "status": "pending",
  "amount": 1000,
  "currency": "USD",
  "created_at": "2025-11-24T12:00:00Z"
}


curl -X POST "https://api.citicapitol.com/v1/payouts" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "account_id": "acct_123",
  "amount": 1000,
  "currency": "USD",
  "reference": "Invoice #456"
}'


import fetch from "node-fetch";

const response = await fetch(
  "https://api.citicapitol.com/v1/payouts",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer <YOUR_API_KEY>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      account_id: "acct_123",
      amount: 1000,
      currency: "USD",
      reference: "Invoice #456"
    })
  }
);

console.log(await response.json());


$payload = json_encode([
  "account_id" => "acct_123",
  "amount" => 1000,
  "currency" => "USD",
  "reference" => "Invoice #456"
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.citicapitol.com/v1/payouts");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer <YOUR_API_KEY>",
  "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

print_r($response);


import requests

response = requests.post(
  "https://api.citicapitol.com/v1/payouts",
  headers={
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json"
  },
  json={
    "account_id": "acct_123",
    "amount": 1000,
    "currency": "USD",
    "reference": "Invoice #456"
  }
)

print(response.json())

POST /v1/collections

The Collections API allows businesses to initiate fund pulls directly from customer deposit accounts. Common use cases include subscription billing, invoice settlement, rent collection, recurring payments, and merchant pull-authorized transfers.

When a collection request is submitted, Citicapitol Bank verifies:

The customer account exists and is authorized
Sufficient balance is available
The request matches your authorization scope
No fraud or compliance flags are triggered

Collections may process instantly or asynchronously. Depending on your business profile, you may also configure multi-level approval rules and notification workflows.

Request Body


{
  "customer_account": "acct_789",
  "amount": 500,
  "currency": "USD",
  "description": "Monthly subscription"
}

Response


{
  "collection_id": "col_abc123",
  "status": "initiated",
  "amount": 500,
  "currency": "USD",
  "created_at": "2025-11-24T12:05:00Z"
}


curl -X POST "https://api.citicapitol.com/v1/collections" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "customer_account": "acct_789",
  "amount": 500,
  "currency": "USD",
  "description": "Monthly subscription"
}'


import fetch from "node-fetch";

const response = await fetch(
  "https://api.citicapitol.com/v1/collections",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer <YOUR_API_KEY>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      customer_account: "acct_789",
      amount: 500,
      currency: "USD",
      description: "Monthly subscription"
    })
  }
);

console.log(await response.json());


$payload = json_encode([
  "customer_account" => "acct_789",
  "amount" => 500,
  "currency" => "USD",
  "description" => "Monthly subscription"
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.citicapitol.com/v1/collections");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer <YOUR_API_KEY>",
  "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

print_r($response);


import requests

response = requests.post(
  "https://api.citicapitol.com/v1/collections",
  headers={
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json"
  },
  json={
    "customer_account": "acct_789",
    "amount": 500,
    "currency": "USD",
    "description": "Monthly subscription"
  }
)

print(response.json())

GET /v1/reconciliation

Enterprise clients require automated reporting for auditing, financial mapping, settlement tracking, and variance detection. The Reconciliation API provides a structured financial report of every payout, collection, refund, reversal, chargeback, adjustment, and fee applied to your account.

Reports can be downloaded by date range, batch ID, transaction type, business wallet, or custom metadata filters. Data returned is suitable for ingestion into ERP platforms, BI dashboards, treasury accounting systems, and automated settlement processors.

Query Parameters


?start_date=2025-11-01&end_date=2025-11-24

Response


{
  "report_id": "recon_123",
  "transactions": [
    {"transaction_id":"txn_abc123","status":"completed","amount":1000},
    {"transaction_id":"txn_def456","status":"failed","amount":500}
  ],
  "generated_at": "2025-11-24T12:10:00Z"
}


curl -X GET \
"https://api.citicapitol.com/v1/reconciliation?start_date=2025-11-01&end_date=2025-11-24" \
-H "Authorization: Bearer <YOUR_API_KEY>"


import fetch from "node-fetch";

const response = await fetch(
  "https://api.citicapitol.com/v1/reconciliation?start_date=2025-11-01&end_date=2025-11-24",
  {
    headers: {
      "Authorization": "Bearer <YOUR_API_KEY>"
    }
  }
);

console.log(await response.json());


$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,
  "https://api.citicapitol.com/v1/reconciliation?start_date=2025-11-01&end_date=2025-11-24"
);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer <YOUR_API_KEY>"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

print_r($response);


import requests

response = requests.get(
  "https://api.citicapitol.com/v1/reconciliation",
  headers={"Authorization": "Bearer <YOUR_API_KEY>"},
  params={
    "start_date": "2025-11-01",
    "end_date": "2025-11-24"
  }
)

print(response.json())

Webhooks

Webhooks allow real-time event push notifications from Citicapitol Bank to your backend system. When a payout completes, a collection fails, or a fraud block is triggered, an HTTPS POST request is sent to the webhook endpoint you registered in your dashboard.

Webhooks eliminate the need for continuous polling and are critical for:

Updating internal dashboards
Notifying customers through SMS/email
Triggering automated settlement rules
Triggering workflow engines (e.g., ERP, BPM, or treasury systems)

Your endpoint must return HTTP 200 OK within 10 seconds. Any failure results in retry attempts with exponential back-off for up to 24 hours.

Webhook Payload Example


POST https://your-server.com/webhooks

{
  "event": "transaction.completed",
  "transaction_id": "txn_abc123",
  "status": "completed"
}


curl -X POST "https://your-server.com/webhooks" \
-H "Content-Type: application/json" \
-d '{
  "event": "transaction.completed",
  "transaction_id": "txn_abc123",
  "status": "completed"
}'


app.post("/webhooks", (req, res) => {
  console.log("Webhook received:", req.body);
  res.status(200).send("OK");
});


$data = json_decode(file_get_contents("php://input"), true);
file_put_contents("webhook.log", print_r($data, true));
http_response_code(200);
echo "OK";


from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks", methods=["POST"])
def webhook():
    payload = request.json
    print("Webhook received:", payload)
    return "OK", 200

Error Responses

Citicapitol returns structured error objects for all failing requests. Each error contains a machine-readable code, a short human message, an HTTP status code, and optional diagnostic details to help troubleshooting. Surface errors directly in your UI or log them for reconciliation — but never expose internal diagnostic tokens to end users.

When possible the API will include a request_id and help_url in error payloads so you can trace the request with support. For production incidents include the request_id when contacting Citicapitol support for faster triage.

Common Error Response


{
  "status": "error",
  "code": "invalid_request",
  "message": "The account_id field is required",
  "details": {
    "field": "account_id",
    "reason": "missing"
  },
  "request_id": "req_01F3X4",
  "status_code": 400,
  "timestamp": "2025-11-24T14:00:00Z"
}


curl -i -X POST "https://api.citicapitol.com/v1/payouts" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount":1000}'  # missing account_id
# Check HTTP status and JSON body for 'code' and 'request_id'


const res = await fetch("https://api.citicapitol.com/v1/payouts", { method: "POST", headers, body });
if (!res.ok) {
  const err = await res.json();
  console.error("API error:", err.code, err.message, "request:", err.request_id);
  // show friendly message to user
}


$resp = curl_exec($ch);
$http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$data = json_decode($resp, true);
if ($http >= 400) {
  error_log("API error: {$data['code']} - {$data['message']} (request: {$data['request_id']})");
}


r = requests.post(url, headers=headers, json=payload)
if r.status_code >= 400:
    err = r.json()
    print("API error:", err.get("code"), err.get("message"), "req:", err.get("request_id"))

Rate Limiting

To preserve overall platform stability, Citicapitol enforces rate limits per API key and per endpoint. Limits are applied as a rolling window and may vary by plan. When a limit is exceeded the API returns a 429 response with a retry_after value in seconds.

Implement exponential backoff on retries and respect the Retry-After header. For high-volume use cases, contact your Citicapitol account manager to discuss an Enterprise plan with elevated limits and dedicated capacity.

Headers to Monitor


X-RateLimit-Limit: 120
X-RateLimit-Remaining: 23
X-RateLimit-Reset: 1699340400   # epoch seconds when window resets


curl -I "https://api.citicapitol.com/v1/payouts" \
-H "Authorization: Bearer YOUR_API_KEY"
# Look for X-RateLimit-* headers in response


const res = await fetch(url, { headers });
console.log("Limit:", res.headers.get("X-RateLimit-Limit"));
console.log("Remaining:", res.headers.get("X-RateLimit-Remaining"));


$headers = curl_getinfo($ch);
echo $headers['request_header'];
// or inspect response headers returned by your HTTP client


r = requests.get(url, headers=headers)
print(r.headers.get("X-RateLimit-Remaining"))

Status Code Breakdown

Citicapitol follows conventional HTTP semantics. The status code is your primary signal for route behavior (success vs. client vs. server error). Use the status code plus the error code field to drive programmatic handling.

2xx — Success. Action completed or accepted (200, 201).
4xx — Client error. Fix request and retry if appropriate (400, 401, 403, 404, 409).
5xx — Server error. Retry with backoff and alert support if persistent (500, 503).

Combine status code checks with the API's machine-readable code string for fine-grained flows (e.g. insufficient_balance, rate_limit_exceeded, validation_failed).


curl -i "https://api.citicapitol.com/v1/payouts/txn_abc123" \
-H "Authorization: Bearer YOUR_API_KEY"
# HTTP/1.1 200 OK
# or HTTP/1.1 404 Not Found


const res = await fetch(url, { headers });
if (res.status === 404) { console.log("Not found"); }
else if (res.status >= 500) { /* retry */ }


$http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($http === 404) { /* handle */ }
elseif ($http >= 500) { /* retry/backoff */ }


r = requests.get(url, headers=headers)
if r.status_code == 404:
    print("Not found")
elif r.status_code >= 500:
    # retry with backoff

Essential

High-Yield

Citicapitol CD

Premier

Everyday

Direct Access

Interest

Premier Advantage

API Documentation

Authentication

OAuth2 — Client Credentials (Machine-to-Machine)

Token Request

Token Response

POST /v1/payouts

Request Body

Response

POST /v1/collections

Request Body

Response

GET /v1/reconciliation

Query Parameters

Response

Webhooks

Webhook Payload Example

Error Responses

Common Error Response

Rate Limiting

Headers to Monitor

Status Code Breakdown

Account Created Successfully 🎉

Pending Compliance Review

Access Restricted

Essential Savings

High-Yield Savings

Citicapitol CD

Premier Savings

Everyday Checking

Direct Access Checking

Interest Checking

Premier Advantage Checking

API Documentation

Authentication

OAuth2 — Client Credentials (Machine-to-Machine)

Token Request

Token Response

POST /v1/payouts

Request Body

Response

POST /v1/collections

Request Body

Response

GET /v1/reconciliation

Query Parameters

Response

Webhooks

Webhook Payload Example

Error Responses

Common Error Response

Rate Limiting

Headers to Monitor

Status Code Breakdown

Account Created Successfully 🎉

Pending Compliance Review

Access Restricted