API Reference

Base URL and conventions

Everything lives under two hosts. The sandbox mirrors production exactly — same endpoints, same objects, same failure modes — so you can build against it with confidence and switch by changing one key.

• All requests must be made over HTTPS. Plain HTTP is rejected, not redirected.
• Request bodies are JSON. Send Content-Type: application/json.
• Amounts are integers in the currency's smallest unit — 4280 is $42.80.
• Timestamps are RFC 3339 in UTC, e.g. 2026-07-27T09:14:22Z.
• Every object has a prefixed id (ch_, cus_, po_) so you always know what you are holding.

# Create a charge in the sandbox
curl https://api.sandbox.bearmerchant.com/v1/charges \
  -u sk_test_51H8xQ2p: \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ea01-4f2b-9c39-1b7d2a6c0e11" \
  -d '{
    "amount": 4280,
    "currency": "usd",
    "payment_method": "pm_card_visa",
    "description": "Order #1042"
  }'

Core endpoints

The resources most integrations touch. Every collection endpoint supports the same pagination and filtering parameters described below.

Charges

Customers and payment methods

Subscriptions and payouts

Disputes

The charge object

Charges are the object you will handle most. A successful response looks like this:

{
  "id": "ch_3PkX9a2eZvKYlo2C",
  "object": "charge",
  "amount": 4280,
  "amount_refunded": 0,
  "currency": "usd",
  "status": "succeeded",
  "captured": true,
  "description": "Order #1042",
  "customer": "cus_9Fq2LmTd",
  "payment_method": {
    "id": "pm_1KdY7x",
    "brand": "visa",
    "last4": "4242",
    "exp_month": 8,
    "exp_year": 2027
  },
  "outcome": {
    "network_status": "approved_by_network",
    "risk_level": "normal",
    "risk_score": 8,
    "three_d_secure": "authenticated"
  },
  "metadata": { "order_id": "1042" },
  "created": "2026-07-27T09:14:22Z"
}

Create charge parameters

Idempotency

Any POST can be retried safely by sending an Idempotency-Key header. If a request with that key has already succeeded, the original response is replayed instead of creating a second charge.

curl https://api.bearmerchant.com/v1/charges \
  -u sk_live_…: \
  -H "Idempotency-Key: 8f14e45f-ea01-4f2b-9c39-1b7d2a6c0e11" \
  -d '{ "amount": 4280, "currency": "usd", "payment_method": "pm_1KdY7x" }'

# Send the identical request again — you get the same charge back,
# not a second one, and the response carries Idempotent-Replayed: true

Pagination and filtering

List endpoints are cursor-paginated. Pass the id of the last object you saw as starting_after to fetch the next page — offsets are not used, so pages stay stable while new objects arrive.

{
  "object": "list",
  "url": "/v1/charges",
  "has_more": true,
  "data": [ { "id": "ch_3PkX9a2eZvKYlo2C", /* … */ } ]
}

Errors

Errors use conventional HTTP status codes and always return a body describing what went wrong and, where the problem is fixable, which parameter caused it.

{
  "error": {
    "type": "card_error",
    "code": "insufficient_funds",
    "message": "The card has insufficient funds to complete this charge.",
    "decline_code": "51",
    "charge": "ch_3PkX9a2eZvKYlo2C",
    "doc_url": "https://bearmerchant.com/api-reference#errors"
  }
}

Rate limits

Limits are applied per account, not per key, and are generous enough that normal traffic never touches them. Every response carries your current position so you can pace yourself before being throttled.

• Read endpoints: 100 requests per second.
• Write endpoints: 50 requests per second.
• Bulk exports and reporting: 10 requests per second.
• Retry a 429 with exponential backoff and jitter — a tight retry loop will keep you throttled.