Bolrach Pay

Before you start

Sign in at bolrach.com with Authvio, open Pay and set up the business. Test mode works straight away. Live payments open once Authvio has checked the owner and the business, and payouts need a bank account in the business's own name. The Activation tab in Pay shows which of those steps are done.

1. Make a test key

In Developers > API keys, choose New API key. Give it a name that says what uses it, tick Pay with both of its permissions (payments:read and payments:write) and leave the mode on Test. Pay asks for a fresh sign-in before it makes the key. It is shown once, so it goes into the server's secrets straight away. We keep only a hash.

export BOLRACH_KEY=bk_test_...   # from Developers > API keys, shown once

A test key starts bk_test_ and a live one bk_live_. Keys made before the move to one key system start sk_test_ or sk_live_ and keep working. The key decides the mode: nothing in a request body can turn a test key into a live one. A live payments key can only be made once the business is verified.

2. Check the key

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

# {"companyId":"...","env":"test","scopes":["payments:read","payments:write"]}

A missing or revoked key gets 401. A key without the permission a route needs gets 403, and the message names the scope it lacks.

3. A payment link, with no code on your side

Amounts are whole minor units sent as a string, so "250000" is ₦2,500.00. They are strings because some JSON parser along the way would otherwise read a large number as a float.

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"
}

The url opens the same checkout every Bolrach payment uses.

4. A payment from your server

When the merchant's own site sells something, its server creates a payment intent for the order and sends the buyer to its checkout_url. The Idempotency-Key header is required. Save one key per payment attempt before sending the request, and send the same key again if the response is lost. The replay returns the first result instead of a second charge.

curl -s -X POST https://api.bolrachpay.com/v1/payment_intents \
  -H "Authorization: Bearer $BOLRACH_KEY" \
  -H "Idempotency-Key: order-1042-payment-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "120000",
    "currency": "NGN",
    "return_url": "https://merchant.example/orders/1042",
    "description": "Order 1042",
    "client_reference_id": "order-1042",
    "customer": { "email": "buyer@example.com" }
  }'

The answer carries id, status and checkout_url. After paying, the buyer comes back to the return_url. Treat that visit as a hint only, and read the payment from the server:

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

Ship when status is succeeded and the amount, currency and mode match the order you saved. If you would rather we host a fuller checkout page, with the buyer's details and a choice of method, use a hosted checkout session instead.

5. See what happened

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

Every figure comes from a double-entry ledger, so a payment, its fee and its refund always add up. To hear about a payment the moment it settles, add a webhook endpoint.

Next

• Hosted checkout: send the buyer to a page we host, then confirm the order on your server.
• Webhooks: signed events, and how a server checks the signature before it trusts one.
• Refunds: full and partial refunds, retries and what each status means.
• Test mode and test cards: a test card for each outcome, plus Nigerian test bank accounts for payouts.