Take your first payment

Six lines

If you already have a key, this is the whole thing. The walk-through below is the same calls, explained.

curl -s -X POST https://api.bolrachpay.com/v1/payment_intents \
  -H "Authorization: Bearer $BOLRACH_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount":"250000","currency":"CAD","return_url":"https://example.com/thanks"}'

# The intent returns a checkout_url. Send the buyer there, then read the result:
curl -s https://api.bolrachpay.com/v1/payment_intents/$INTENT_ID \
  -H "Authorization: Bearer $BOLRACH_KEY"

# Or receive it: every settlement is delivered to your webhook endpoints, signed.

1 · Get a key

Keys belong to a merchant, not to the platform, so they are minted in the merchant console under Developers. A key is shown once at creation.

# In the merchant console: Developers -> Create key.
# Keys are shown ONCE. A test key starts sk_test_, a live key sk_live_ — the
# prefix is the mode, so a key cannot be moved between them by accident.
export BOLRACH_KEY=sk_test_...

Test and live are separate worlds: the key’s prefix decides which, and the API never takes the mode from your request body. A test key cannot move live money and a live key cannot write to the test ledger.

2 · Prove the key works

curl -s https://api.bolrachpay.com/v1/ping \
  -H "Authorization: Bearer $BOLRACH_KEY"

# {"ok":true,"service":"bolrach","version":"v1"}

A missing or revoked key answers 401; a key without the scope answers 403. Both say which, so you are never guessing.

3 · Create a payment link

The fastest way to charge: a hosted page you can send to anyone. Amounts are integer minor units, as a string — "250000" is NGN 2,500.00. They are strings because a JSON parser somewhere between you and us will otherwise turn a large integer into a float, and money does not survive that.

curl -s -X POST https://api.bolrachpay.com/v1/payment_links \
  -H "Authorization: Bearer $BOLRACH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "August workshop ticket",
    "amount": "250000",
    "currency": "NGN"
  }'

{
  "object": "payment_link",
  "id": "pl_9f2c4a1b8e7d6c5f",
  "mode": "test",
  "url": "https://pay.bolrach.com/t/64645dc7...",
  "name": "August workshop ticket",
  "amount": "250000",
  "currency": "NGN",
  "kind": "one_time",
  "status": "active"
}

Open url in a browser and you are in the same checkout every Bolrach payment uses.

4 · Or charge directly

If you have your own page, create an intent instead. The Idempotency-Key header is required — money movement has to survive a retry without happening twice, so replaying a key returns the original result rather than charging again.

curl -s -X POST https://api.bolrachpay.com/v1/payment_intents \
  -H "Authorization: Bearer $BOLRACH_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "250000",
    "currency": "CAD",
    "return_url": "https://example.com/thanks",
    "customer": { "email": "[email protected]" }
  }'

The response carries a checkout_url for the hosted 3-D Secure page. In test mode, "request_3ds": "any" forces a challenge so you can exercise that path deliberately.

Which currencies route today: an intent goes to a real processor, so it can only be created in a currency an enabled processor supports — CAD, USD, GBP and EUR in test mode right now. Ask for one it cannot route and you get a 400 saying exactly that, rather than an intent that fails later. Payment links have no such limit: they price in any currency and route when the buyer opens them.

5 · Read what happened

curl -s https://api.bolrachpay.com/v1/payments \
  -H "Authorization: Bearer $BOLRACH_KEY"

Every figure the API returns comes from the double-entry ledger, not a counter kept beside it — which is why a payment, its fee and its refund always agree.

The contract

The full machine-readable spec is at https://api.bolrachpay.com/v1/openapi.json, generated from the same list the API routes from, so it cannot drift into describing endpoints that do not exist. The human catalogue is at https://api.bolrachpay.com/v1.

Other Bolrach APIs — Geo, AI, Identity and the rest — serve from api.bolrach.io and use platform keys. Payments keys are per-merchant and stay on the payments host.