CaliBear Credit Union — API Documentation

Getting Started

Before you can call the API, you need to register and get your credentials.

Go to www.calibear.credit and fill out the registration form.
You'll instantly receive a clearinghouse_id and an api_key.
Use those credentials to start sending transaction requests.

Save your API key immediately! It will not be shown again after registration. Store it somewhere safe and do not commit it to a public repo.

Endpoint

POST https://api.calibear.credit/transaction/

Trailing slash required! Make sure your URL ends with /transaction/ — without the trailing slash you'll get a 404.

Required Headers

Header	Value	Description
`Content-Type`	`application/json`	Tells us you're sending JSON.
`x-api-key`	Your API key	Your secret credential token. Starts with `credential_token_`. This goes in the header, not the body.

Body Parameters

Send these fields as a JSON object in the body of your POST request:

Field	Type	Required	Description
`clearinghouse_id`	string	Yes	Your unique clearinghouse identifier (starts with `CH-`).
`card_number`	string	Yes	The 16-digit card number. Send as a string, don't strip leading zeros.
`amount`	number	Yes	Dollar amount. Must be a positive number (e.g., `150.75`). Not a string.
`transaction_type`	string	Yes	`"withdrawal"` or `"deposit"`. Lowercase only.
`merchant_name`	string	Yes	Name of the merchant (e.g., `"Walmart"`).

Authentication

Your API key goes in the request header as x-api-key, not in the body. Your clearinghouse_id goes in the body. Both are required on every request.

We pull x-api-key from your header and clearinghouse_id from the body.
We look up your clearinghouse in our database.
If it doesn't exist, the key doesn't match, or your account has been revoked, we return 401.
If everything checks out, we process the transaction.

Transaction Processing Logic

Withdrawals (Debit Accounts)

Look up account by card_number
Check account status is active
Check daily transaction limit (sum of today's approved withdrawals + this amount)
Check that amount does not exceed available balance
If all pass → APPROVED, deduct from balance

Withdrawals (Credit Accounts)

Look up account by card_number
Check account status is active
Check daily transaction limit
Check that current balance + amount does not exceed credit limit
If all pass → APPROVED, add to amount owed

Deposits (Either Account Type)

Look up account by card_number
Check account status is active
For debit: add amount to available balance
For credit: subtract amount from what's owed (like a payment)
Generally APPROVED if account exists and is active

Example Requests

Withdrawal (Debit Card Purchase)

Customer buying $42.50 at Walmart with their debit card:

curl -X POST "https://api.calibear.credit/transaction/" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "clearinghouse_id": "YOUR_CLEARINGHOUSE_ID",
    "card_number": "9594406409097439",
    "amount": 42.50,
    "transaction_type": "withdrawal",
    "merchant_name": "Walmart"
  }'

Withdrawal (Credit Card Purchase)

Customer charging $250.00 at Best Buy on their credit card:

curl -X POST "https://api.calibear.credit/transaction/" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "clearinghouse_id": "YOUR_CLEARINGHOUSE_ID",
    "card_number": "2104709521456232",
    "amount": 250.00,
    "transaction_type": "withdrawal",
    "merchant_name": "Best Buy"
  }'

Deposit (Merchant Receiving Payment)

Merchant account receiving $150.00 from a sale:

curl -X POST "https://api.calibear.credit/transaction/" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "clearinghouse_id": "YOUR_CLEARINGHOUSE_ID",
    "card_number": "9594406409097439",
    "amount": 150.00,
    "transaction_type": "deposit",
    "merchant_name": "Target"
  }'

Replace the placeholder values! Use the clearinghouse_id and api_key you received when you registered at www.calibear.credit.

Response Format

Successful Transaction 200

{
  "message": "APPROVED",
  "transaction_id": "a3f1c2d4-5678-9abc-def0-1234567890ab",
  "card_number": "9594406409097439",
  "amount": 42.50,
  "transaction_type": "withdrawal",
  "new_balance": 48287674.50
}

Declined Transaction 403

{
  "message": "DECLINED - INSUFFICIENT_FUNDS",
  "card_number": "9594406409097439",
  "amount": 999999999.00,
  "transaction_type": "withdrawal"
}

Unauthorized 401

{
  "message": "Unauthorized - invalid api key"
}

Bad Request 400

{
  "message": "Bad Request - missing required field(s): card_number, merchant_name"
}

HTTP Status Codes

Code	Meaning	When It Happens
200	OK — Approved	Transaction went through successfully.
400	Bad Request	Missing fields, invalid amount, or bad transaction_type.
401	Unauthorized	Credentials missing, wrong, or revoked.
403	Declined	Business rule rejection (see message for reason).
404	Not Found	Card number doesn't exist in our system.
500	Server Error	Something broke on our end. Try again.

Decline Reasons

When a transaction is declined (403), the message field tells you exactly why:

Message	What It Means
`DECLINED - INSUFFICIENT_FUNDS`	Debit withdrawal exceeds available balance.
`DECLINED - CREDIT_LIMIT_EXCEEDED`	Credit withdrawal would exceed credit limit.
`DECLINED - DAILY_LIMIT_EXCEEDED`	Today's total would exceed the daily limit.
`DECLINED - ACCOUNT_FROZEN`	Account is frozen.
`DECLINED - ACCOUNT_CLOSED`	Account has been closed.
`DECLINED - ACCOUNT_OVERDRAWN`	Account is overdrawn.

Troubleshooting

Problem	What to Check
Getting `404` on the endpoint	Make sure your URL ends with `/transaction/` (trailing slash required).
Getting `401 Unauthorized`	Check that `x-api-key` is in the header (not body). Check `clearinghouse_id` is in the body. Both are case-sensitive.
Getting `400 Bad Request`	Send all 5 body fields. Make sure `amount` is a number not a string. `transaction_type` must be `"withdrawal"` or `"deposit"` exactly.
Getting `404` on a card	The card number doesn't exist. Check you're using the right 16-digit number as a string.
Getting `403 Declined`	Read the `message` field — it tells you exactly why.
Getting `500`	Server error. Try again. If it persists, contact us.
Request hangs	Make sure you're sending POST not GET. Verify both headers are set.
JSON parse error	Check for trailing commas, unquoted keys, or invalid JSON.
Don't have credentials	Go to www.calibear.credit and register.

Quick Reference

POST https://api.calibear.credit/transaction/

Headers

Content-Type: application/json
x-api-key: your-credential-token-here

Body

{
  "clearinghouse_id": "CH-your-id-here",
  "card_number": "1234567890123456",
  "amount": 42.50,
  "transaction_type": "withdrawal",
  "merchant_name": "Store Name"
}

Outcomes

200 Approved 400 Bad request 401 Auth failed 403 Declined 404 Not found 500 Server error