diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..eec8a86
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+type: Bug
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..bbcbbe7
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
diff --git a/README.md b/README.md
index e638f31..a0f488e 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add this to your application's Gemfile:
 
 ```ruby
 gem "paystack-ruby"
@@ -34,10 +34,22 @@ Or install directly:
 gem install paystack-ruby
 ```
 
+---
+## Configuration
+
+`Paystack::Client` takes your secret key as its only argument:
+
+```ruby
+paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
+```
+Use your Test Secret Key (`sk_test_...`) for development and Live Secret Key (`sk_live_...`) in production. Get them from your [Paystack Dashboard](https://dashboard.paystack.com/#/login).
+
 ---
 
 ## Quick Start
 
+Initialize a transaction and send the customer to `authorization_url` to pay:
+
 ```ruby
 require "paystack"
 
@@ -53,19 +65,16 @@ result = paystack.transaction.initialize(
 puts result.data[:authorization_url]
 ```
 
----
-
-## Configuration
-
-Initialize `Paystack::Client` with your secret key:
+Once the customer is redirected back, verify the transaction before you treat it as paid; never trust the redirect alone:
 
 ```ruby
-paystack = Paystack::Client.new("sk_live_xxxxxxxxxxxx")
+result = paystack.transaction.verify(reference)
+
+if result.data[:status] == "success"
+  # fulfil the order
+end
 ```
 
-| Option | Type | Required | Default |
-|---|---|---|---|
-| `api_key` | `String` | ✅ | — |
 
 ---
 
@@ -85,21 +94,28 @@ response.meta        # Hash / nil
 
 ## Error Handling
 
-API failures raise typed exceptions:
+API failures raise a `Paystack::Error`, carrying the HTTP status and response body:
 
 ```ruby
 begin
   paystack.transaction.initialize({ email: "customer@example.com", amount: 100_000 })
-rescue Paystack::AuthenticationError,
-       Paystack::ValidationError,
-       Paystack::NotFoundError,
-       Paystack::RateLimitError,
-       Paystack::ServerError => e
+rescue Paystack::Error => e
   puts e.message
   puts e.http_status
 end
 ```
 
+If you need to branch on failure type, rescue the specific subclass instead — `Paystack::AuthenticationError`, `ValidationError`, `NotFoundError`, `RateLimitError`, or `ServerError`:
+
+```ruby
+begin
+  paystack.transaction.initialize({ email: "customer@example.com", amount: 100_000 })
+rescue Paystack::RateLimitError
+  sleep(1)
+  retry
+end
+```
+
 ---
 
 ## API Reference